Polis is an AI powered sentiment gathering platform. More organic than surveys and less effort than focus groups, Polis meets the basic human need to be understood, at scale.
For a detailed methods paper, see Polis: Scaling Deliberation by Mapping High Dimensional Opinion Spaces.
If you're interested in contributing to the codebase, please see the following:
- ✅ issues: for well-defined technical issues
- 💬 discussions: for questions about the software, or more open ended ideas and conversation which don't properly fit in issues
- Our Project Board is somewhat incomplete, but still useful; We stopped around the time that Projects Beta came out, and we have a Projects Beta Board that we'll eventually be migrating to
The recommended path for deploying Polis is to use the Docker & Docker Compose infrastructure contained in this repository.
In particular, the ./docker-compose.yml file describes a basic Polis topology sufficient for relatively small deployments.
The main limitation of this setup is that it only provisions a single server node, while a very active Polis conversation of tends of thousands of participants (or several smaller simultaneous sized conversations) could require multiple server nodes. Thus, you may need to look into alternative solutions (Heroku, Kubernetes, etc.) if you expect to exceed this level of usage. In either case, you can take advantage of the underlying Docker infrastructure, sans docker-compose (see the wiki for info on how to run on Heroku). That having been said, it is our goal to support scalable deployments out of the box, and we'd be happy to accept pull requests which get us closer to this goal.
The one additional piece you'll need to handle yourself for a production deployment is SSL encryption. Our goal is to streamline this as much as possible (see #289), so again if you'd like to help with this, please submit a PR!
- See also: Deployment: About SSL/HTTPS
With all that out of the way, deploying a small Polis instance using the docker-compose infrastructure looks more or less like the development environment setup below, with one exception: Instead of running docker-compose -f docker-compose.yml -f docker-compose.dev.yml ..., you run docker-compose -f docker-compose.yml ... (or simply docker-compose, since -f defaults to docker-compose.yml).
Any configuration options which are explicitly for development are placed in the docker-compose.dev.yml overlay, and can be omitted in production.
The doc at docs/deployment.md is currently somewhat out of date, but may provide additional useful details.
If you would like more help that you're able to get in the public channels above, we encourage your to reach out to us.
The recommended way of setting up a development environment is to use docker-compose.
The only prerequisite is that you install docker (and Docker Desktop if you are on Mac).
Newer versions of docker have docker compose built in as a subcommand.
If you are using an older version (and don't want to upgrade), you'll need to separately install docker-compose.
After cloning the repository, navigate via command line to the root directory and run the following command to build and run the docker containers:
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --buildIf you get a permission error, try running this command with sudo.
If this fixes the problem, sudo will be necessary for all other commands as well.
To avoid having to use sudo in the future (on a Linux or Windows machine with WSL), you can follow setup instruction here: https://docs.docker.com/engine/install/linux-postinstall/.
Once you've built, you can run the following when you want to run the project:
docker compose -f docker-compose.yml -f docker-compose.dev.yml upThat's it!
You can now test your setup by visiting http://localhost:80/.
Once the index page loads, you can create an account using the /createuser path. You'll be logged in right away; email validation is not required.
The system should start running without any configuration. However, as you go on (and especially if you are setting up a production deployment), you'll need to know how to configure the application.
At the moment, there are a number of configuration files and environment variable options scattered across the repository. There is currently an open PR which seeks to unify the configuration options which we're actively working on: compdemocracy#1341
If you plan on running a large conversations or lots of conversations at once, you might bump into performance issues.
Assuming that the host has enough resources to run multiple instances of the polis server container, you can start polis using the following command:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --scale server=3Where 3 is the number of replicas you'd like to use.
Due to past file re-organizations, you may find the following git configuration helpful for looking at history:
git config --local include.path ../.gitconfig
To force a full re-build with no cache from previous builds you can run with --no-cache.
When you're done working, you can end the process using Ctrl+C.
If you would like to run docker compose as a background process, run the up commands with the --detach flag, e.g.,:
docker-compose up --detach
And to stop:
docker-compose down
https://github.com/compdemocracy/polis/wiki/Using-Docker-Machine-as-your-development-environment
We use Cypress for automated, end-to-end browser testing! (See badge above.)
Please see e2e/README.md and https://github.com/compdemocracy/polis/wiki/Running-E2E-tests-locally.
Sometimes npm/docker get in a weird state, especially with native libs, and fail to recover gracefully.
You may get a message like Error: Cannot find module .... bcrypt.
If this happens to you, try following the instructions here: