This repo contains a basic docker-compose configuration for running Loomio on your own server.
It assumes you want to run everything on a single host. It automatically issues an SSL certificate for you via the amazing letsencrypt.org.
-
Root access to a server, on a public IP address, running a default configuration of Ubuntu 14.04 x64.
-
A domain name which you can create DNS records for.
-
An SMTP server for sending email. More on that below.
What hostname will you be using for your Loomio instance? What is the IP address of your server?
For the purposes of this example, the hostname will be loomio.example.com and the IP address is 123.123.123.123
To allow people to access the site via your hostname you need an A record:
A loomio.example.com, 123.123.123.123
You also need to setup a CNAME record for the live update service
CNAME faye.loomio.example.com, loomio.example.com
Loomio supports "Reply by email" and to enable this you need an MX record so mail servers know where to direct these emails.
MX loomio.example.com, loomio.example.com, priority 0
To login to the server, open a terminal window and type:
ssh -A [email protected]
These commands install docker and docker-compose, copy and paste.
wget -qO- https://get.docker.com/ | sh
wget -O /usr/local/bin/docker-compose https://github.com/docker/compose/releases/download/1.12.0/docker-compose-`uname -s`-`uname -m`
chmod +x /usr/local/bin/docker-compose
This is the place where all the configuration for your Loomio services will live. In this step you make a copy of this repo, so that you can modify the settings to work for your particular setup.
As root on your server, clone this repo:
git clone https://github.com/loomio/loomio-deploy.git
cd loomio-deploy
The commands below assume your working directory is this repo, on your server.
There are some simple scripts within this repo to help you configure your server.
This script will create and mount a 4GB swapfile. If you have less than 2GB RAM on your server then this step is required.
./scripts/create_swapfile
This script creates env
and faye_env
files configured for you. It also creates directories on the host to hold user data.
When you run this, remember to change loomio.example.com
to your hostname, and give your contact email address, so you can recover your SSL keys later if required.
./scripts/create_env loomio.example.com [email protected]
Now have a look inside the files:
cat env
and
cat faye_env
By default your Loomio instance will report back to www.loomio.org with the number of discussions, comments, polls, stances, users and visits that your site has had.
Once per day it will send those numbers and your hostname to us, so that we are able to measure Loomio usage around the world, so that we can tell what impact our work is having.
If you wish to disable this reporting function, add the following line to your env
file
DISABLE_USAGE_REPORTING=1
Loomio is technically broken if it cannot send email. In this step you need to edit your env
file and configure the SMTP settings to get outbound email working.
So, you'll need an SMTP server. If you already have one, that's great, you know what to do. For everyone else here are some options to consider:
-
For setups that will send less than 99 emails a day use smtp.google.com for free.
-
Look at the (sometimes free) services offered by SendGrid, SparkPost, Mailgun, Mailjet.
-
Soon we'll publish a guide to setting up your own private and secure SMTP server.
Edit the env
file and enter the right SMTP settings for your setup.
You might need to add an SPF record to indicate that the SMTP can send mail for your domain.
nano env
This command initializes a new database for your Loomio instance to use.
docker-compose run loomio rake db:setup
Doing this tells the server what regular tasks it needs to run. These tasks include:
- Noticing which proposals are closing in 24 hours and notifying users.
- Closing proposals and notifying users they have closed.
- Sending "Yesterday on Loomio", a digest of activity users have not already read. This is sent to users at 6am in their local timezone.
The following command appends some lines of text onto the system crontab file.
cat crontab >> /etc/crontab
This step is optional, and by default loomio will let users create an account. However, it's often easier for them to use their login on other social media. Loomio integrates and allow authentication with any site that offer oauth, like google (eg login with their gmail credentials) or facebook.
edit your env file, and for each provider adds two line.
{{provider}}_APP_KEY
"{{provider}}_APP_SECRET
So, if you want to let users login directly from facebook and google, , in your .env file put
```sh
GOOGLE_APP_KEY=app_key
GOOGLE_APP_SECRET=*app_secret
FACEBOOK=app_key
FACEBOOK_APP_SECRET=app_secret
On both google and facebook, you need to create an app to register your loomio
Check the documentation for each provider.
For Facebook, you simply have to [register loomio as an app](https://developers.facebook.com)
For twitter, [create your app](https://apps.twitter.com/)
- Website : **https://loomio.example.com**
- callback url: **https://loomio.example.com/twitter/authorize**
For Google, it's less smooth, feel free to skip this provider for now and add it later
- (create your credentials in the [console](https://console.developers.google.com/) (for a web application)
-- Authorized JavaScript origins: **https://loomio.example.com**
-- Authorized redirect URIs: **https://loomio.example.com/google/authorize**
- domain verification: https://loomio.example.com
## Starting the services
This command starts the database, application, reply-by-email, and live-update services all at once.
docker-compose up -d
You'll want to see the logs as it all starts, run the following command:
docker-compose logs
You might like to keep an additional console open by your side to watch for potential errors or warnings:
docker-compose logs -f
## Try it out
visit your hostname in your browser. something like `https://loomio.example.com`.
You should see a login screen, but instead sign up at `https://loomio.example.com/users/sign_up`
Once you have signed it (and confirmed your email), grant yourself admin rights
```sh
docker exec -ti loomiodeploy_db_1 su - postgres -c 'psql loomio_production'
loomio_production=# update users set is_admin=true where email = '[email protected]';
UPDATE 1
loomio_production=# \q
you should now see the admin interface at https://loomio.example.com/admin
## Test the functionality
Test that email is working by visiting `https://loomio.example.com/users/password/new` and get a password reset link sent to you.
Test that live update works with two tabs on the same discussion, write a comment in one, and it should appear in the other.
Test that you can upload files into a thread.
Test that you can reply by email.
test that proposal closing soon works.
## If something goes wrong
Confirm `env` and `faye-env` settings are correct.
After you change your `env` or `faye-env` files you need to restart the system:
```sh
docker-compose down
docker-compose up -d
To update Loomio to the latest image you'll need to stop, rm, pull, apply potential changes to the database schema, and run again.
docker-compose down
docker-compose pull
docker-compose run loomio rake db:migrate
docker-compose up -d
From time to time, or if you are running out of disk space (check /var/lib/docker
):
docker rmi $(docker images -f "dangling=true" -q)
To login to your running rails app console:
docker exec loomiodeploy_worker_1 bundle exec rails console
A PostgreSQL shell to inspect the database:
docker exec -ti loomiodeploy_db_1 su - postgres -c 'psql loomio_production'
Most of the environment we have set up so far can be considered disposable, as it can be rebuilt from scratch in a few minutes.
Things you want to consider when designing a proper backup policy:
loomio-deploy/uploads
loomio-deploy/env
loomio-deploy/faye-env
And a database dump:
docker exec -ti loomiodeploy_db_1 su - postgres -c 'pg_dump loomio_production' \
| xz \
> $(date +%Y-%m-%d_%H:%M).pg_dump.xz
Be sure you exclude loomio-deploy/pgdata
โ all you need from the database is in the dump.
Need some help? Visit the Installing Loomio group.