If you use the Citizen OS open source code, please let us know: info@citizenos.com! <3 We are mostly interested in the usage statistics. Perhaps you can open the stats for us?

Citizen OS is a free participation platform for collaborative text creation, structured discussion and voting. Read about the newest developments on our news page: https://citizenos.com/news/.

:dart: Features

• Private and public groups and topics
• e-ID log-in and vote signing
• Science-led structured argumentation environment
• vote delegation, minivote, multiple choices votes
• bottom-up empowerment
• Independently funded by a sustainable NGO
• GDPR compliant
• Multi-platform UI
• activity feed
• Community moderation
• Translated in 14 languages
• And much more, explore Citizen OS

:bulb: Philosophy

The Citizen OS Foundation is a civic tech non-profit organisation based in Tallinn, Estonia.

Our mission is “to empower as many people as possible to participate in respectful, meaningful discussions in order to collaboratively decide on issues that affect their wellbeing."

The main focus of the Citizen OS Foundation is our collaborative decision-making platform for civic initiatives, which is provided free of charge to anyone who wants to use it. The online platform allows for deliberative discussions, collaborative decision-making and voting in situations where it is either impossible or inconvenient for participants to be in the same room.

In Estonia, where a national e-ID system is in place, the Citizen OS platform is also used in situations when a large number of people need to digitally sign a single document, such as people's initiatives, petitions, housing associations agreements and NGO general meetings. Documents signed using the Citizen OS platform are accepted by all levels of government, including the Riigikogu (Estonia’s Parliament) and the national Commercial Register.

We listen to our users in issues.

:eyes: Installation

TOC:

• Running locally
  • Prerequisites
  • Installing
  • Running
  • Updating
  • Testing
  • Debugging
• Contributing
  • Pull requests
• Improvement ideas

:book: Running locally

:pencil2: Prerequisites

• Understand the architecture of CitizenOS platform
• Software
  • Node.JS >= 6.13.1 (https://github.com/mklement0/n-install)
  • PostgreSQL >= 9.5
  • Etherpad-Lite - https://github.com/citizenos/etherpad-lite-heroku. See the README.md and use the config/local.json.example as a basis to get the right plugin configuration.
  • OPTIONAL: 7zip (https://www.7-zip.org/) - 7z executable in PATH. Used to generate BDOC-s wrapped in ZIP, initially used and designed for containers sent to Estonian Parliament. To install on Debian/Ubuntu (apt-get install p7zip-full).

:gear: Installing

• Get the source - git clone git@github.com:citizenos/citizenos-api.git
• Go to the source directory - cd citizenos-api
• Install dependencies - npm install
• Add to dev.api.citizenos.com to your hosts file - sudo -- sh -c -e "echo '127.0.0.1 dev.api.citizenos.com' >> /etc/hosts"
• Create the DB:

  sudo su -c "DATABASE_URL=postgres://citizenos:citizenos@localhost:5432/citizenos npm run dbcreate" postgres

• Create DB user:
  • NOTE: DO NOT use this in production, you may want different privileges!

    sudo su -c "psql -c \"CREATE USER citizenos WITH PASSWORD 'citizenos'\"" postgres
    sudo su -c "psql -c \"GRANT ALL PRIVILEGES ON DATABASE citizenos TO citizenos\"" postgres

:gear: Configuration

We use https://github.com/lorenwest/node-config.

Configuration files are in ./config directory.

Order of applying, further down the list overrides value from the sources above it:

• default.json - Global configuration that is same for all environments.
• {process.env.NODE_ENV}.json - Environment specific overrides.
• local.json - Your local configuration that you create your self. This file is for YOUR SPECIFIC overrides, the file is in .gitignore so you don't accidentally commit it.
• ENV - configuration values defined in environment variables. What can be overwritten there, can be read from custom-environment-variables.json

Examples of Citizen OS API configuration: https://github.com/citizenos/citizenos-api/wiki/Configuration

:zap: Running

• Start the app - npm start
• By default API is available https://dev.citizenos.com:3003 or over plain HTTP http://dev.api.citizenos.com:3002.

NOTES:

• When using over HTTPS you need to add ./config/certs/citizenosCARoot.pem to your trusted CA certificate store or browsers will complain.

:hourglass: Updating

You need to do the following to update Citizen OS on your server:

• Pull new code from GitHub. Production environments should use prod branch.
• Run migrations on your DB to apply DB changes - https://github.com/citizenos/citizenos-api/wiki/DB-Migrations

:microscope: Testing

• You need an instance of citizenos-api and etherpad-lite running before you execute tests.
• npm test

:beetle: Debugging

• By default logs are in ./logs/app.log

:warning: Issues

FATAL ERROR: Committing semi space failed. Allocation failed - process out of memory

Node.JS runs out of memory. This can be solved by tuning the garbage collection (GC) of Node.JS runtime via V8 options.

• --max-old-space-size - Max size of the old generation (in Mbytes). By default it's 1.5GB. Set it to amount that is maximum that you want Node.JS process to allocate. Example: node --max-old-space-size=250 ./bin/www

Reading:

• All available V8 options - https://gist.github.com/sarupbanskota/a68e8148aa4cdc95e66a1b0e93df48ef

Endpoint GET "/api/auth/google/callback" failed miserably. Status: undefined Stack: InternalOAuthError: failed to fetch user profile

Google+ API is not enabled. Enable Google+ API at https://console.developers.google.com/apis/library/plus.googleapis.com by clicking "ENABLE".

:book: Contributing

Pull requests

• All pull requests to master branch
• Live site runs on prod branch
• All the other ways to contribute - https://citizenos.com/get-involved/

DB changes

DB changes require migrations, please read https://github.com/citizenos/citizenos-api/wiki/DB-Migrations

:book: Improvement ideas

• Support different authentication and signing methods so that anyone could add their country specifics. That takes us to modular architecture where ideally I would like to add new methods by installing a module and configuring it.
• Implement generic "if this, then that" engine where anyone can plug into Topic state changes with their own custom logic. Right now for example Rahvaalgatus.ee has a flow where a signed document is sent to Parliament via e-mail, but this is very region/partner specific.
• Email layout designing should be much simpler. Right now there is hard-coded CitizenOS layout and special layout for Rahvaalgatus.ee. We may consider using MailChimp or other services so that there is a separate service where mails are designed and sent and for which each Partner pays themselves.
• ...