This is a quick reference to get DemocracyOS up and running.


To get started with DemocracyOS, you will need to have installed:


To run it on Windows you must use Docker. In the develop section there's a tutorial on how to use it.


Unix and OS/X

  • Fork or download this repository.
  • cd to the project's location
  • Run make packages
  • Set up your configuration, and add your email as staff to be able to initialize your app.
  • Make sure MongoDB is running and reachable as configured in config/development.json. (Default values should work)
  • Run make
  • Boom! DemocracyOS should be running on port 3000.

Please refer to the Configuration section to customize settings


Once DemocracyOS components and dependencies are installed, you can start the application like this:

make run

Take a look at the Makefile for more information about the possible tasks you can run.

You can check the current DemocracyOS version going to http://localhost:3000/api

Using SSL

In case you want to use SSL in your dev environment (it's disabled by default), you'll need to have proper certificate files. We ship a script that generates the needed files. Just run the following command in the project root:

NODE_PATH=. node bin/dos-ssl

Then modify your configuration file by changing the protocol property to https and run it normally. Configuration options for SSL are listed here.

A note on using port 443

The default configuration file make the app listens to port 443 to handle SSL connections. In some OSs, a normal user cannot perform this operation, and you are likely to get this error:

       throw er; // Unhandled 'error' event
Error: bind EACCES
   at errnoException (net.js:904:11)
   at net.js:1072:30
   at Object.37:1 (cluster.js:594:5)

To solve it without being root (that is always a bad idea), you can change the ssl.port value in your configuration file to another port, say 4443.

Running in production environment

  1. Configure your environment variables for production; specifically, set NODE_ENV to production
  2. Set your JWT_SECRET environment variable to something random. e.g.: Any of this.
  3. Set your MongoDB instance to run as a service.
  4. Make sure to correctly configure the Notifier for production environments.
  5. From the project's root path, you need to run make or:
  6. npm install to install node dependencies.
  7. npm run build && npm run start to build assets and run the app. Don't run as sudo.

If something goes wrong you can always go back to a clean slate running make clean.

OS specifics

  • Check this very detailed guide if you're on Ubuntu 10 LTS.
  • On Ubuntu 14/13/lower, install the package node-legacy for NodeJS.
  • Check this guide on how to run DemocracyOS as a service.

Running unit tests

To run unit tests simply run

npm test

A running MongoDB instance is required to perform tests. By default, the DemocracyOS-test database is used and all its data is wiped on each run. If you want to override the database, just run the above command prefixing MONGO_URL=<database uri>. For example:

MONGO_URL=mongodb://localhost/other-db npm test

Loading sample data

In order for you to see a fully working deployment, you will need some sample data. This can be achieved by either of these approaches: Manually load sample fixtures bundled with DemocracyOS. Setup and access the administration module.