Skip to main content



This guide will help you with all you need to set-up and deploy CitizenLab Open-Source. While having some experience with the command line and configuring servers will come in handy, but we'll try to guide you through it.

1. Set-up a VPS 🆘 help

This guide was written for Ubuntu 20.04, a Digital Ocean tutorial to set it up can be found here.

If you decide to run your database on the same server, as this guide assumes, we recommend a server with at least 4GB of RAM memory.

2. Install docker 🆘 help

Official docs

Digital Ocean docs

$ sudo apt-get update

$ sudo apt-get install -y \
apt-transport-https \
ca-certificates \
curl \
gnupg \

$ curl -fsSL | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

$ echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

$ sudo apt-get update

$ sudo apt-get install -y docker-ce docker-ce-cli

$ sudo usermod -aG docker ${USER}

$ docker --version

To apply the new group membership, log out of the server and back in, otherwise docker may not work properly.

3. Install docker-compose 🆘 help

Official docs

Digital Ocean docs

$ sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

$ sudo chmod +x /usr/local/bin/docker-compose

$ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

$ docker-compose --version

4. Clone the repository 🆘 help

We've provided a Github repository with a minimal premade configuration to run the platform on a single server.

$ sudo apt-get install -y git

$ git clone

$ cd citizenlab-docker

5. Provide configuration values 🆘 help

Before we can launch the application, we need to provide configuration values. You can choose some of these values yourself, but for some you will need to create external accounts. All configuration values need to be provided in the .env file.


You can edit the .env file straight on the server using a command line text editor. Nano is a good, easy to user one. Type nano .env to open it.

5.1 Secrets 🆘 help

In order to provide the application with strong internal passwords for the database and user authentication, we have provided a script that generates them for you.

$ sh

5.2 Admin user 🆘 help

Provide the initial email, password, first and last name of the admin user. You can only set them here initially, once the application has started this no longer has an effect.

# ***** USER  *****

5.3 Domain name and DNS 🆘 help

CL_SETTINGS_HOST= controls the domain name of your platform.

To configure the domain name, you should change the setting and configure your DNS hosting provider to direct traffic towards the server. The docker-compose setup provides auto-provisioning https, by using Caddy as the webserver, so the connection will always be secure. Adding the A and AAAA DNS records for your domain name, towards your server, is enough to make it work.

# The address of the platform, without https://

Caddy doesn't work with an IP address out of the box. If you provide an IP address for CL_SETTINGS_HOST instead of a domain name, your browser will error with ERR_SSL_PROTOCOL_ERROR or similar when visiting. To test whether the platform works before having a domain name configured, you can edit the Caddyfile and add http:// in front of {$CL_SETTINGS_HOST}. Don't ever use http for a production platform though!

5.4 Timezone 🆘 help

Set the timezone for your application, a list of valid timezones can be found here.


5.5 Email 🆘 help

The platform sends out email notification and has an email engine to send manual campaigns to user groups. For this to work, you need to provide the smtp server information.

Here's an example for gmail, but any provider that supports SMTP works.

# Delete the `#` in front of the keys to uncomment them, and fill in the appropriate values
# SMTP_DOMAIN= # this could also be

Your username and password will be in plain-text on the .env file, please consider creating a dedicated account solely for the purpose of sending out emails from the platform.

Alternatively, Mailgun is also supported, in which case you'll need to provide the API key and the domain.

# Delete the `#` in front of the keys to uncomment them, and fill in the appropriate values
# Optional, defaults to

5.6 Maps 🆘 help

The CitizenLab platform displays maps in various places. The configuration allows you to specify the map center, expressed in latitude and longitude, and the map zoom level.

You can also provide the tile provider, which defaults to open streetmap.

Finally, in case you want to let people position their inputs on a map, you'll also need to provide a google maps API key.

# Delete the `#` in front of the key to uncomment it, and fill in the appropriate value

5.7 Other 🆘 help

The .env file contains some additional variables to set up social logins, or integrate some extra services. Over time, more values will be added.

6. Pull images 🆘 help

This step may take a while since it will download all images needed to run the project.

Official docs

$ docker-compose pull

7. Initialize the database 🆘 help

Almost ready for action. When all configuration is provided, we're ready to setup the database.

$ docker-compose run --rm web rake db:setup

If you get errors, it's likely that you didn't provide all configuration values in step 5.

8. Run it! 🚀 🆘 help

Official docs

$ docker-compose up -d

It can take a few minutes before the platform starts to respond.


Official docs

$ docker-compose stop

Checking the logs

Official docs

$ docker-compose logs