HTTPS

DemocracyOS allows securing client-server communication via TLS by allowing your server to listen to HTTPS requests.

Server setup

In order to enable TLS you will need the appropriate certificate and public encryption key for the domain where your server will be hosting the application. THESE ARE NOT THINGS WE CAN PROVIDE FOR YOU.

For information on how to acquire certificates read this Wikipedia entry.

Once you have your certificate and key, place them under an ssl directory, in the application root directory. They should be named server.crt and server.key, respectively. This should look like:

$you@server: pwd
/path/to/your/app/dir/ssl

$you@server: ls
server.crt   server.key

Configuration settings

There are three relevant setting for configuring TLS in your server:

• Server protocol.
• Port where the server will listen for incoming HTTPS requests.
• HTTP to HTTPS redirection strategy.

These settings are dependent on how you're handling your server configuration (either by config file or by environment variables). We'll only cover environment variables here since it's the desired approach for production servers; setting this up with a config file should be pretty straightforward by looking at config/defaults.json.

Protocol

Just set the PROTOCOL variable to https and the server will listen for HTTPS requests in the configured port.

Port

Set up HTTPS_PORT where you want the server to listen for incoming HTTPS requests. By default this is set to 443, but remember you need to run the application with administrative privileges for binding to the default port.

HTTPS enforcement and redirection strategy

DemocracyOS supports HTTP to HTTPS automatic redirection by default. We do this with express-sslify. This works by listening for HTTP requests on a diffrerent port and re-routing those requests to the secure server. However, depending on you deployment architecture/enviroment, you may want to tweak how redirection works. You can do this by setting the HTTPS_REDIRECT enviroment variable to one of the following values:

• normal: performs a plain simple redirection from any HTTP request to the same path, but under HTTPS. This is the default mode.
• reverse-proxy: this is to allow redirection behind reverse proxies. This is useful when running on platforms such as Heroku, Nodejitsu, Joyent, etc.
• azure: special strategy for if your servers are in the Microsoft Azure cloud platform.
• no-redirect: performs no redirection at all. Unless you have some other means of redirection or you want the application to be completely unaccessible via HTTP requests, you shouldn't use this.

Development and self-signed certificates

You may run a HTTPS server using self-signed certificates. These won't do for production environments but are useful for trying out stuff in a development environment.

NOTE: for this you'll need to have OpenSSL installed and available from your PATH.

Generate self-signed certificates by running the bin/dos-certs script from your project's root path. This will generate a pair of server.crt and server.key files under the ssl directory. After that just run the server with PROTOCOL set to https and you should be able to reach your local build under https://localhost