Vokomokum deployment setup

This is the production setup for Vokomokum, a food cooperative in Amsterdam, NL for: members, finances and ordering.

If you want to run it for yourself, see setup, or if you'd like to modify the configuration, please proceed to common tasks.

Please note that this is currently under development.

Setup

Foodsoft

At this moment, you'l need to build the vokomokum/foodsoft yourself (this will change in the future).

git clone https://github.com/vokomokum/foodsoft.git /tmp/foodsoft
cd /tmp/foodsoft
docker build -t vokomokum/foodsoft:latest .

Stack

To get the stack running yourself, you need to provide the private information via environment variables to docker-compose. Here is an example to build and start the project locally:

export DOMAIN=vkmkm.localhost
export HOSTNAME_ORDER=order.vkmkm.localhost
export HOSTNAME_MEMBERS=members.vkmkm.localhost
export MEMBERS_DB_PASSWORD=secret_mb
export SMTP_DB_PASSWORD=secret_ms
export FOODSOFT_DB_PASSWORD=secret_fs
export FOODSOFT_SECRET_KEY_BASE=1234567890abcdefghijklmnoprstuvwxyz
export MYSQL_ROOT_PASSWORD=mysql
export SHAREDLISTS_DB_PASSWORD=secret_sl
export SHAREDLISTS_SECRET_KEY_BASE=abcdefghijklmnopqrstuvwxyz1234567890
export VOKOMOKUM_CLIENT_SECRET=secret_cc
# remove the following line on production when ready
export CERTBOT_DISABLED=1

docker-compose build --pull
docker-compose pull
docker-compose up -d

You can also store the variables in .env instead.

The above setup should work on a development machine. Depending on your setup, you may need to point order.vkmkm.localhost and members.vkmkm.localhost in your /etc/hosts to 127.0.0.1.

Initial database setup

On first time run, you'll need to setup the database. Start and connect to it as root:

docker-compose up -d mariadb redis
docker exec -it vkmkm-deploy_mariadb_1 mysql -u root -p

Then run the following SQL commands:

-- create foodsoft database
CREATE DATABASE foodsoft_vkmkm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci;
GRANT ALL ON foodsoft_vkmkm.* TO foodsoft@'%' IDENTIFIED BY 'secret_fs';

-- create sharedlists database
CREATE DATABASE sharedlists CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci;
GRANT ALL ON sharedlists.* TO sharedlists@'%' IDENTIFIED BY 'secret_sl';
GRANT SELECT ON sharedlists.suppliers TO foodsoft@'%';
GRANT SELECT ON sharedlists.articles TO foodsoft@'%';

-- create members database
CREATE DATABASE members CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci;
GRANT ALL ON members.* TO members@'%' IDENTIFIED BY 'secret_mb';

Subsequently you need to populate the databases:

docker-compose run --rm foodsoft bundle exec rake db:setup db:migrate
docker-compose run --rm sharedlists bundle exec rake db:setup
docker-compose run --rm members ./dbsetup.py

Then finalize SQL setup for the SMTP server (run mysql as before):

GRANT SELECT ON members.members TO smtp@'%' IDENTIFIED BY 'secret_ms';
GRANT SELECT ON members.workgroups TO smtp@'%';
GRANT SELECT ON members.wg_leadership TO smtp@'%';
GRANT SELECT ON members.wg_membership TO smtp@'%';

Finally you may want to load some dummy data into Foodsoft:

docker-compose run --rm foodsoft bundle exec rake db:drop db:create db:schema:load db:migrate db:seed:small.nl

SSL certificates

By default, a dummy SSL certificate will be generated (for localhost). This is useful for development, and to bootstrap easily.

For production, you need proper SSL certificates. These are provided by letsencrypt. Set DOMAIN and make sure the DNS is setup correctly. Then remove CERTBOT_DISABLED=1 from the environment and restart the certbot instance.

Deployment

Deployment happens by running a script on the server, which pulls the latest changes from the remote repository, rebuilds the docker images and runs them when needed.

You need to clone the repository and configure it for group access:

git clone --config core.sharedRepository=true https://github.com/vokomokum/vkmkm-deploy.git
chgrp -R docker vkmkm-deploy
chmod -R g+sw vkmkm-deploy

Finally, setup a daily cronjob to ensure security updates for the docker images:

echo `readlink -f deploy.sh` > /etc/cron.daily/deploy.sh
chmod u+x /etc/cron.daily/deploy.sh

Mail delivery

To be able to send emails, you need a mail relay. Point the SMTP_ADDRESS and SMTP_PORT environment variables to the relay. When authentication is required, also set SMTP_USER_NAME and SMTP_PASSWORD.

When testing mail delivery, you wouldn't want to deliver real emails. Instead, you can use mailcatcher and see all outgoing mails in a web-interface. To use it, uncomment the relevant lines on docker-compose.yml, and set SMTP_ADDRESS to mailcatcher and SMTP_PORT to 25. Open a webbrowser on http://localhost:1080/ and you're set.

Common tasks

• Deploying
• Upgrading Foodsoft

Deploying

When you've made a change to this repository, you'll likely want to deploy it to production. First push the changes to the Github repository, then run deploy.sh on the server.

Upgrading Foodsoft

Note: this section has not been tested yet!

To update Foodsoft to a new version:

• Update version in number in foodsoft/Dockerfile
• Look at the changelog to see if anything is required for migrating, and prepare it.
• Test it locally, especially our customizations. Don't forget this!
• Deploy
• Without delay, run database migrations and restart the foodsoft images.

cd /home/deploy/vkmkm-deploy
docker-compose run --rm foodsoft bundle exec rake db:migrate
docker-compose restart foodsoft foodsoft_worker foodsoft_smtp