Kobo Docker Deployment on Ubuntu Server


Greetings I have been trying to deploy Kobo for over a month now and cant seem to get it working. I have generated SSL keys and placed them in secrets directory and such forth but nothing seems to be working. Containers keep reporting errors.

How can I get help? Is there any contractors available for helping with deployment? I have posted issues on github not getting any responses. Please let me know.

here is an issue I created https://github.com/kobotoolbox/kobo-docker/issues/220


Hi Nobusier,

Have you figured it out?

I am having quite some issue with the SSL certificates as I do not understand how to generate them for each subdomain. Dunno if I should be using letencrypt or openssl … and how to chain them in the ssl.crt and ssl.key

Any idea or tips?

Thanks in advance.


Hi @michel-pierre and @nobiuser ,

I think I can help with the certificate generation. I helped deploy a couple of Kobo Docker instances recently, and getting a good workflow for SSL was the hardest part (and not well documented!). Here’s what worked for me:

  1. Setup DNS. The primary domain and all 3 subdomains should point at the server’s IP.
  2. Install Certbot on the server (guide for Ubuntu here).
  3. Use the ‘standalone’ option to generate the certificate. Kobo Docker needs a single certificate that covers the primary domain and all 3 subdomains. You can create that with:
    sudo certbot certonly --standalone -d example.com -d kc.example.com -d kf.example.com -d en.example.com.
  4. Copy the certificate files into the /secrets folder for Kobo Docker to access:
sudo cp /etc/letsencrypt/live/example.com/fullchain.pem /path/to/kobo-docker/secrets/ssl.crt
sudo cp /etc/letsencrypt/live/example.com/privkey.pem /path/to/kobo-docker/secrets/ssl.key

(Check these are the right way round! Certbox also gives you a cert.pem. I tried using this at first, but when that failed I used the fullchain.pem, which worked.)
5. Start the Kobo Docker:

cd /path/to/kobo-docker/
docker-compose up -d

All this should get the server running with SSL. Then comes the task of automating the certificate renewal. Certbot’s certificates are good for 90 days.

My solution was a shell script to pause the nginx server within kobo docker, renew the certificate, copy the files into /secrets, then restart nginx. See below for an example. I run this every month via a cron job.

There’s probably a better way to do this - one that doesn’t involve any server down-time, but this method works fine for me.

I hope this helps - Even if it doesn’t, It give me something to refer to when I need to setup another kobo docker server in a year or so!)

Kind regards,

Script for renewing SSL certificate.

# Stop current kobo-nginx
cd /opt/kobo-docker
docker-compose stop nginx

# Renew certificates
certbot renew

cp /etc/letsencrypt/live/example.com/fullchain.pem /opt/kobo-docker/secrets/ssl.crt
cp /etc/letsencrypt/live/example.com/privkey.pem /opt/kobo-docker/secrets/ssl.key

# Start kobo-nginx again
docker-compose up -d
  • save as ssl-renew.sh.
  • make it executable: `sudo chmod +x ssl-renew.sh
  • add to cron: sudo crontab -e, then add the following line:
    0 0 1 * * /opt/ssl-renew.sh