This guide will help you with all you need to set-up and deploy CitizenLab. While having some experience with the command line and configuring servers will come in handy, but we'll try to guide you through it.
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.
To apply the new group membership, log out of the server and back in, otherwise docker may not work properly.
We've provided a Github repository with a minimal premade configuration to run the platform on a single server.
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
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.
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.
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.
CL_SETTINGS_HOST= controls the domain name of your platform. To start off, you could just set it to the external IP address of your server and access it like that.
To configure the proper 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.
Set the timezone for your application, a list of valid timezones can be found here.
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.
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.
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.
.env file contains some additional variables to set up social logins, or integrate some extra services. Over time, more values will be added.
This step may take a while since it will download all images needed to run the project.
Almost ready for action. When all configuration is provided, we're ready to setup the database.
If you get errors, it's likely that you didn't provide all configuration values in step 5.
It can take a few minutes before the platform starts to respond.