Polis

⚠️ We are migrating to New Implementation -> Chorus and archiving this repo!

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

What is Polis?

Polis is a platform for gathering, analyzing, and understanding sentiment at scale. It uses AI to help facilitate large-scale, open-ended discussions.

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

Quick Links 🪁 🎈

• Main Deployment: https://pol.is (Free for nonprofits and governments)
• CivicTech Deployment (This Fork): https://civictech-polis.azurewebsites.net/
• Knowledge Base (Wiki): https://compdemocracy.org/Welcome (Comprehensive user guide)
• Discussions (Q&A): https://github.com/compdemocracy/polis/discussions
• Technical Issues: https://github.com/compdemocracy/polis/issues
• High-Impact Support: mailto:hello@compdemocracy.org (For significant deployments requiring more support)
• Community Support: https://github.com/CivicTechTO/polis/issues
• Talk to a person / Polis 101 : https://civictech.ca (Join CivicTech Hacknight - Ask for a Polis 101)
• CivicTech Slack: https://civictech.ca (Join the #polis channel)

Getting Started (For Developers & Deployers)

This section is for those who want to run their own instance of the CivicTech fork of Polis or contribute to development.

Polis comes with Docker infrastructure for running a complete system, whether for a production deployment or a development environment.

Quick Start (Development)

Open terminal and enter:

cp example.env .env
make start

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

Visit http://localhost:80/createuser 🚀

Detailed Instructions

• Running Polis: See Running Polis below for more details.
• Configuration: See docs/configuration.md for deployment configuration.
• Deployment: See docs/deployment.md for deployment bash commands.
• Contributing: See CONTRIBUTING.md for how to contribute upstream polis main repository.
• Contributing: See our wiki for how to contribute to this fork.

Running Polis

Polis uses Docker and Docker Compose for easy setup.

Prerequisites

• Docker and Docker Compose installed. Instructions for avoiding sudo with Docker.

Basic Commands

• Start (Development): make start (Equivalent to docker compose --profile postgres up)
• Start (Rebuild): make start-rebuild (Rebuilds Docker images)
• Start (Production - see docs/deployment.md for complete instructions): make PROD start (Requires prod.env)
• Stop: make stop (Equivalent to docker compose --profile postgres down)
• Help: make help (Lists available commands)
• View Configuration: docker compose --profile postgres convert
• Full Rebuild (Use with caution - wipes database): make start-FULL-REBUILD

Using a local or remote (non-docker) database

See Using a local or remote (non-docker) database below

💻 Development Mode

For development, use the following command to enable live code reloading, debugging, and other conveniences:

docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile postgres up --build

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

About docker compose overlay file:

• docker-compose.dev.yml in above command is an overlay file, which layers the developer conveniences describe above into the base system, as described in the docker-compose.yml file.
• You can create your own docker-compose.x.yml file as an overlay and add or modify any values you need to differ from the defaults found in the docker-compose.yml file and pass it as the second argument to the docker compose -f command above.
• 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 --profile postgres up).

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.

Testing

• End-to-End (E2E) Tests: See e2e/README.md for instructions on running automated browser tests.

Troubleshooting

• Docker Issues: Try restarting Docker, killing all containers, or using make start-FULL-REBUILD (WARNING: This wipes the database).
• NPM Issues: See this issue for potential solutions.
• Apple Silicon (M1/M2) Issues: You may need to use a Rosetta terminal for some dependencies.

License

AGPLv3 with additional permission under section 7