Polis

Polis is an AI powered sentiment gathering platform. More organic than surveys and less effort than focus groups.

For a detailed methods paper, see Polis: Scaling Deliberation by Mapping High Dimensional Opinion Spaces.

<!-- Changes to badge text in URLs below, require changes to "name" value in .github/workflows/*.yml -->

---

🎈 🪁 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

• 🌐 main deployment: the main deployment of Polis is at https://pol.is, and is free to use for nonprofits and government

• 💬 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, whether for a production deployment or a development environment (details for each can be found in later sections of this document). As a consequence, the only prerequisite to running Polis is that you install a recent docker (and Docker Desktop if you are on Mac or Windows).

If you aren't able to use Docker for some reason, the various Dockerfiles found in subdirectories (math, server, delphi, *-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.

Quick Start

1. Install and Configure SSL Certificates

Polis uses locally trusted SSL certificates for the OIDC authentication simulator. This is a one-time setup:

# Install mkcert (macOS with Homebrew)
brew install mkcert
brew install nss  # if you use Firefox

# Other platforms: https://github.com/FiloSottile/mkcert#installation

# Install the local Certificate Authority
mkcert -install

# Generate certificates for localhost
mkdir -p ~/.simulacrum/certs
cd ~/.simulacrum/certs
mkcert -cert-file localhost.pem -key-file localhost-key.pem localhost 127.0.0.1 ::1 oidc-simulator host.docker.internal

# Copy the root CA certificate (needed for server-to-server communication)
cp "$(mkcert -CAROOT)/rootCA.pem" ~/.simulacrum/certs/

Important: After running mkcert -install, completely restart your browser to trust the certificates.

2. Generate JWT Keys

Polis uses JWT keys for participant authentication. Generate them with:

make generate-jwt-keys

This creates server/keys/jwt-private.pem and server/keys/jwt-public.pem.

3. Start Polis

cp example.env .env
make start

That should run docker compose with the development overlay (see below) and default configuration values.

You may encounter an error on mac if AirPlay receiver is enabled, which defaults to port 5000 and collides with Polis API_SERVER_PORT. You can change this in your .env file or disable AirPlay receiver in system settings.

Visit localhost:80/createuser and get started.

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.

Many convenient commands are found in the Makefile. Run make help for a list of available commands.

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.

Copy the example.env file and modify as needed (although it should just work as is for development and testing purposes).

cp example.env .env

docker compose --profile postgres --profile local-services 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 instructions here.

Once you've built the docker images, you can run without --build, which may be faster. Run

docker compose --profile postgres --profile local-services up

or simply

make start

Any time you want to rebuild the images, just reaffix --build when you run. Another way to easily rebuild and start your containers is with make start-rebuild.

If you have only changed configuration values in .env, you can recreate your containers without fully rebuilding them with --force-recreate. For example:

docker compose --profile postgres --profile local-services down
docker compose --profile postgres --profile local-services up --force-recreate

To see what the environment of your containers is going to look like, run:

docker compose --profile postgres --profile local-services convert

Using a local or remote (non-docker) database

Omit the --profile postgres flag to use a local or remote database. You will need to set the DATABASE_URL environment variable in your .env file to point to your database.

When using make commands, setting POSTGRES_DOCKER to true or false will determine whether to automatically include --profile postgres when it calls out to docker compose.

Production Mode Shortcuts

The commands in the Makefile can be prefaced with PROD. If so, the "dev overlay" configuration in docker-compose.dev.yml will be ignored. Ports from services other than the HTTP proxy (80/443) will not be exposed. Containers will not mount local directories, watch for changes, or rebuild themselves. In theory this should be one way to run Polis in a production environment.

You need a prod.env file:

cp example.env prod.env (and update accordingly).

Then you can run things like:

make PROD start

make PROD start-rebuild

Running without Local Cloud Service Emulators

If you want to run the stack without the local MinIO and DynamoDB services (e.g., to test connecting to real AWS services configured in your .env file), simply omit the --profile local-services flag.

Example: Run with the containerized DB but connect to external/real cloud services:

docker compose --profile postgres up

Example: Run with an external DB and external/real cloud services (closest to production):

docker compose up

Testing out your instance

You can now test your setup by visiting http://localhost:80/home.

Using Predefined Test Accounts

When running with make start or the development configuration, an OIDC Simulator automatically starts with predefined test users. You can log in immediately using:

• Email: admin@polis.test
• Password: Te$tP@ssw0rd*

Additional test users are available:

• moderator@polis.test / Te$tP@ssw0rd*
• test.user.0@polis.test through test.user.49@polis.test (all with password Te$tP@ssw0rd*)

Due to limitations of the OIDC Simulator, you cannot register new admin users in development and test environments.

Shutting down

When you're done working, you can end the process using Ctrl+C, or typing docker compose --profile postgres --profile local-services down if you are running in "detached mode".

Updating the system

If you want to update the system, you