Polis

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.

🎈 🪁 Start here! 🪁🎈

If you're interested in using or contributing to Polis, please see the following:

• 📚 knowledge base: for a comprehensive wiki to help you understand and use the system
• 💬 discussions: for questions (QA) and discussion
• ✔️ issues: for well-defined technical issues
• 🏗️ project board: 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
• ✉️ reach out: if you are applying Polis in a high-impact context, and need more help than you're able to get through the public channels above

If you're trying to set up a Polis deployment or development environment, then please read the rest of this document 👇 ⬇️ 👇

⚡ Running Polis

Polis comes with Docker infrastructure for running a complete system. As a consequence, the only prerequisite to running Polis is that you install a recent docker (and Docker Desktop if you are on Mac).

If you aren't able to use Docker for some reason, the various Dockerfiles found in subdirectories (math, server, *-client) of this repository can be used as a reference for how you'd set up a system manually. If you're interested in doing the legwork to support alternative infrastructure, please let us know in an issue.

Docker & Docker Compose

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, and use that instead in the instructions that follow. Note however that the newer docker compose command is required to take advantage of Docker Swarm as a scaling option.

Building and running the containers

First clone the repository, then navigate via command line to the root directory and run the following command to build and run the docker containers.

docker compose up --build

If 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 the docker images, you can run without --build, which may be faster. Simply:

docker compose up

Any time you want to rebuild the images, just reaffix --build when you run.

Testing out your instance

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.

When you're done working, you can end the process using Ctrl+C.

Updating the system

If you want to update the system, you may need to handle the following:

• ⬆️ Run database migrations, if there are new such
• Update docker images by running with --build if there have been changes to the Dockerfiles
  • consider using --no-cache if you'd like to rebuild from scratch, but note that this will take much longer

🚀 Production deployment

While the commands above will get a functional Polis system up and running, additional steps must be taken to properly configure, secure and scale the system. In particular

• ⚙️ Configure the system, esp:
  • the domain name you'll be serving from
  • enable and add API keys for 3rd party services (e.g. automatic comment translation, spam filtering, etc)
• 🔏 Set up SSL/HTTPS, to keep the site secure
• 📈 Scale for large or many concurrent conversations

Support

We encourage you to take advantage of the public channels above for support setting up a deployment. However, if you are deploying in a high impact context and need help, please reach out to us

💻 Development tooling

Once you've gotten Polis running (as described above), you can enable developer conveniences by executing:

docker compose up -f docker-compose.yml -f docker-compose.dev.yml

This enables:

• Live code reloading and static type checking of the server code
• A nREPL connection port open for connecting to the running math process
• Ports open for connecting directly to the database container
• Live code reloading for the client repos (in process)
• etc.

This command takes advantage of the docker-compose.dev.yml overlay file, which layers the developer conveniences describe above into the base system, as described in the docker-compose.yml file. You can specify these -f docker-compose.yml -f docker-compose.dev.yml arguments for any docker command which you need to take advantage of these features (not just docker compose up).

Testing

We use Cypress for automated, end-to-end browser testing for PRs on GitHub (see badge above). Please see e2e/README.md for more information on running these tests locally.

Miscellaneous & troubleshooting

Git Configuration

Due to past file re-organizations, you may find the following git configuration helpful for looking at history:

git config --local include.path ../.gitconfig

Running as a background process

If you would like to run docker compose as a background process, run the up commands with the --detach flag, and use docker compose down to stop.

Using Docker Machine as your development environment

If your development machine is having trouble handling all of the docker containers, look into using Docker Machine.

Resolving problems with npm not finding libraries

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:

compdemocracy#1391

©️ License

AGPLv3 with additional permission under section 7