{"id":13511899,"url":"https://github.com/compdemocracy/polis","last_synced_at":"2025-03-30T21:31:13.550Z","repository":{"id":36968728,"uuid":"75125125","full_name":"compdemocracy/polis","owner":"compdemocracy","description":":milky_way: Open Source AI for large scale open ended feedback","archived":false,"fork":false,"pushed_at":"2025-03-25T05:06:37.000Z","size":38011,"stargazers_count":840,"open_issues_count":304,"forks_count":203,"subscribers_count":26,"default_branch":"edge","last_synced_at":"2025-03-25T06:20:05.431Z","etag":null,"topics":["civic-tech","data-science","deliberative-democracy","participatory-democracy"],"latest_commit_sha":null,"homepage":"https://pol.is","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/compdemocracy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-29T21:47:47.000Z","updated_at":"2025-03-23T23:57:26.000Z","dependencies_parsed_at":"2023-11-28T07:24:56.049Z","dependency_job_id":"618e1fcc-9fe1-41b5-a087-88005b5cf864","html_url":"https://github.com/compdemocracy/polis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compdemocracy%2Fpolis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compdemocracy%2Fpolis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compdemocracy%2Fpolis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compdemocracy%2Fpolis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/compdemocracy","download_url":"https://codeload.github.com/compdemocracy/polis/tar.gz/refs/heads/edge","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246385124,"owners_count":20768662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["civic-tech","data-science","deliberative-democracy","participatory-democracy"],"created_at":"2024-08-01T03:01:17.574Z","updated_at":"2025-03-30T21:31:13.544Z","avatar_url":"https://github.com/compdemocracy.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","data-science"],"sub_categories":[],"readme":"# Polis\n\nPolis is an AI powered sentiment gathering platform. More organic than surveys and less effort than focus groups.\n\nFor a detailed methods paper, see [Polis: Scaling Deliberation by Mapping High Dimensional Opinion Spaces][methods-paper].\n\n   [methods-paper]: https://www.e-revistes.uji.es/index.php/recerca/article/view/5516/6558\n\n\u003c!-- Changes to badge text in URLs below, require changes to \"name\" value in .github/workflows/*.yml --\u003e\n[![Docker Image Builds](https://github.com/compdemocracy/polis/workflows/Docker%20image%20builds/badge.svg)][docker-image-builds]\n[![E2E Tests](https://github.com/compdemocracy/polis/workflows/E2E%20Tests/badge.svg)][e2e-tests]\n\n   [docker-image-builds]: https://hub.docker.com/u/compdem\n   [e2e-tests]: https://github.com/compdemocracy/polis/actions?query=workflow%3A%22E2E+Tests%22\n\n---\n\n## 🎈 🪁 Start here! 🪁 🎈\n\nIf you're interested in using or contributing to Polis, please see the following:\n\n- [📚 **knowledge base**][knowledge-base]: for a comprehensive wiki to help you understand and use the system\n- [🌐 **main deployment**](https://pol.is): the main deployment of Polis is at \u003chttps://pol.is\u003e, and is\n  free to use for nonprofits and government\n- [💬 **discussions**][discussions]: for questions (QA) and discussion\n- [✔️ **issues**][issues]: for well-defined technical issues\n- [🏗️ **project board**][board]: somewhat incomplete, but still useful; We stopped around the time that Projects Beta came out, and we have a [Projects Beta Board][beta-board] that we'll eventually be migrating to\n- [✉️ reach out][hello]: 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\n\n   [knowledge-base]: https://compdemocracy.org/Welcome\n   [issues]: https://github.com/compdemocracy/polis/issues\n   [board]: https://github.com/compdemocracy/polis/projects/1\n   [beta-board]: https://github.com/compdemocracy/polis/projects/1\n   [discussions]: https://github.com/compdemocracy/polis/discussions\n   [hello]: mailto:hello@compdemocracy.org\n\nIf you're trying to set up a Polis deployment or development environment, then please read the rest of this document 👇 ⬇️ 👇\n\n---\n\n## ⚡ Running Polis\n\nPolis comes with Docker infrastructure for running a complete system, whether for a [production deployment](#-production-deployment) or a [development environment](#-development-tooling) (details for each can be found in later sections of this document).\nAs 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).\n\nIf 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.\nIf you're interested in doing the legwork to support alternative infrastructure, please [let us know in an issue](https://github.com/compdemocracy.org/issues).\n\n### Quick Start\n\n```sh\ncp example.env .env\nmake start\n```\n\nThat should run docker compose with the development overlay (see below) and default configuration values.\n\nYou 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.\n\nVisit `localhost:80/createuser` and get started.\n\n### Docker \u0026 Docker Compose\n\nNewer versions of `docker` have `docker compose` built in as a subcommand.\nIf 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.\nNote however that the newer `docker compose` command is required to [take advantage of Docker Swarm](/docs/scaling#docker-compose-over-docker-swarm) as a scaling option.\n\nMany convenient commands are found in the Makefile. Run `make help` for a list of available commands.\n\n### Building and running the containers\n\nFirst clone the repository, then navigate via command line to the root directory and run the following command to build and run the docker containers.\n\nCopy the example.env file and modify as needed (although it should just work as is for development and testing purposes).\n\n```sh\ncp example.env .env\n```\n\n\n```sh\ndocker compose --profile postgres up --build\n```\n\nIf you get a permission error, try running this command with `sudo`.\nIf this fixes the problem, sudo will be necessary for all other commands as well.\nTo avoid having to use `sudo` in the future (on a Linux or Windows machine with WSL), [you can follow setup instructions here.](https://docs.docker.com/engine/install/linux-postinstall/)\n\nOnce you've built the docker images, you can run without `--build`, which may be faster. Run\n\n```sh\ndocker compose --profile postgres up\n```\n\nor simply\n\n```sh\nmake start\n```\n\nAny time you want to _rebuild_ the images, just reaffix `--build` when you run. Another way to\neasily rebuild and start your containers is with `make start-rebuild`.\n\nIf you have only changed configuration values in .env, you can recreate your containers without\nfully rebuilding them with `--force-recreate`. For example:\n\n```sh\ndocker compose --profile postgres down\ndocker compose --profile postgres up --force-recreate\n```\n\nTo see what the environment of your containers is going to look like, run:\n\n```sh\ndocker compose --profile postgres convert\n```\n\n#### Using a local or remote (non-docker) database\n\nOmit 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.\n\nWhen 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`.\n\n#### Production Mode Shortcuts\n\nThe commands in the Makefile can be prefaced with PROD. If so, the \"dev overlay\" configuration in `docker-compose.dev.yml` will be ignored.\nPorts from services other than the HTTP proxy (80/443) will not be exposed. Containers will not mount local directories, watch for changes,\nor rebuild themselves. In theory this should be one way to run Polis in a production environment.\n\nYou need a `prod.env` file:\n\n`cp example.env prod.env` (and update accordingly).\n\nThen you can run things like:\n\n```sh\nmake PROD start\n\nmake PROD start-rebuild\n```\n\n### Testing out your instance\n\nYou can now test your setup by visiting `http://localhost:80/home`.\n\nOnce the index page loads, you can create an account using the `/createuser` path.\nYou'll be logged in right away; email validation is not required.\n\nWhen you're done working, you can end the process using `Ctrl+C`, or typing `docker compose --profile postgres down`\nif you are running in \"detached mode\".\n\n### Updating the system\n\nIf you want to update the system, you may need to handle the following:\n\n- [⬆️ Run database migrations](docs/migrations.md), if there are new such\n- Update docker images by running with `--build` if there have been changes to the Dockerfiles\n  - consider using `--no-cache` if you'd like to rebuild from scratch, but note that this will take much longer\n\n---\n\n## 🚀 Production deployment\n\nWhile 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.\nIn particular\n\n- [⚙️ Configure the system](docs/configuration.md), esp:\n  - the domain name you'll be serving from\n  - enable and add API keys for 3rd party services (e.g. automatic comment translation, spam filtering, etc)\n- [🔏 Set up SSL/HTTPS](docs/ssl.md), to keep the site secure\n- [📈 Scale](docs/scaling.md) for large or many concurrent conversations\n\n### Support\n\nWe encourage you to take advantage of the public channels above for support setting up a deployment.\nHowever, if you are deploying in a high impact context and need help, please [reach out to us][hello]\n\n---\n\n## 💻 Development tooling\n\nOnce you've gotten [Polis running (as described above)](#-running-polis), you can enable developer conveniences by running\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml --profile postgres up\n```\n\n(run with `--build` if this is your first time running, or if you need to rebuild containers)\n\nThis enables:\n\n- Live code reloading and static type checking of the server code\n- A nREPL connection port open for connecting to the running math process\n- Ports open for connecting directly to the database container\n- Live code reloading for the client repos (in process)\n- etc.\n\nThis 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.\nYou 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`).\n\nYou can create your own `docker-compose.x.yml` file as an overlay and add or modify any values you need to differ\nfrom the defaults found in the `docker-compose.yml` file and pass it as the second argument to the `docker compose -f` command above.\n\n### Testing\n\nWe use Cypress for automated, end-to-end browser testing for PRs on GitHub (see badge above).\nPlease see [`e2e/README.md`](/e2e/README.md) for more information on running these tests locally.\n\n### Miscellaneous \u0026 troubleshooting\n\n#### Docker Problems\n\nA lot of issues might be resolved by killing all docker containers and/or restarting docker entirely. If that doesn't\nwork, this will wipe all of your polis containers and volumes (**INCLUDING THE DATABASE VOLUME, so don't use this in prod!**) and completely rebuild them:\n\n`make start-FULL-REBUILD`\n\nsee also `make help` for additional commands that might be useful.\n\n#### Git Configuration\n\nDue to past file re-organizations, you may find the following git configuration helpful for looking at history:\n\n```sh\ngit config --local include.path ../.gitconfig\n```\n\n#### Running as a background process\n\nIf you would like to run docker compose as a background process, run the `up` commands with the `--detach` flag, and use `docker compose --profile postgres down` to stop.\n\n#### Using Docker Machine as your development environment\n\nIf your development machine is having trouble handling all of the docker containers, look into [using Docker Machine](/docs/docker-machine.md).\n\n#### Resolving problems with npm not finding libraries\n\nSometimes npm/docker get in a weird state, especially with native libs, and fail to recover gracefully.\nYou may get a message like `Error: Cannot find module .... bcrypt`.\n\nIf this happens to you, try\n[following the instructions here.](https://github.com/compdemocracy/polis/issues/1391)\n\n#### Issues with Apple Silicon (M1 \u0026 M2) chips\n\nYou may find it necessary to install some dependencies, namely nodejs and postgres stuff, in a [Rosetta terminal](https://support.apple.com/en-us/HT211861). Create an issue or reach out if you are having strange build issues on Apple computers.\n\n## ©️  License\n\n[AGPLv3 with additional permission under section 7](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompdemocracy%2Fpolis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcompdemocracy%2Fpolis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompdemocracy%2Fpolis/lists"}