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
1 Like

Hi Degami,

Thank you so much for your response, this has been really helpful and I got it to work now!

Hi Degami,

I tried to run the following command:
sudo certbot --nginx certonly --standalone -d example.com -d kc.example.com, etc

and received the following error:
Could not choose appropriate plugin: Too many flags setting configurators/installers/authenticators ‘nginx’ -> ‘standalone’

Can you assist? Thanks


The key is in the error message:

Too many flags setting configurators/installers/authenticators ‘nginx’ -> ‘standalone’

nginx and standalone are both different ways for Certbot to authenticate. Nginx uses an existing Nginx installation as the server, and standalone creates a temporary server, separate to any existing ones. You cannot use both at the same time.

For Kobotools, I got it working by using standalone. I suspect that’s easier than getting certbot to use the nginx that comes bundled in the Kobotoolbox Docker.

~ D.


So should I uninstall nginx? I installed it separately before anything else was installed.

Yes, I suggest uninstalling Nginx. The Kobo Docker image comes with its own Nginx bundled. I’ve had problems in the past where Kobo won’t start because an existing version of Nginx is hogging the ports. Uninstalling the standalone Nginx should prevent that.

~ D.

Hi, I was finally able to get everything up & running, however when I go to:


ex., kf.example.com

I receive a ‘refused to connect’ error. It’s setup in our public DNS. Firewall is not enabled. Should I configure the built-in nginx?

Hmm. To confirm, is the Kobo Docker running? (started with docker-compose up -d).

Other than that, I’m not sure what could be the issue. The built-in Nginx should configure itself to listen on ports 80 and 443. You could check the status of it with docker-compose ps - that should show all the components’ status and tell you which ports nginx is occupying.

~ D.

Yep, it’s running:

kobo-docker_nginx_1 /sbin/my_init Up>443/tcp,>80/tcp

Does this look correct?


That looks correct, yes. This is a tricky one. I’d suggest 2 avenues to debug:

  1. Check the logs in /path/to/kobo-docker/log/nginx/. Hopefully there’ll be an error.log that’ll give you a hint to what’s going wrong.

  2. If you re-install the standalone nginx and setup a basic web page, can you access that through your subdomains? That might help deteremine if the issue is with the kobo-docker setup or something else.

Good luck! I know these debugging processes can be painfully long…

~ D.

1 Like


Logs in /path/to/kobo-docker/log/nginx reveal:

[emerg] 18873#18873: could not build server_names_hash, you should increase server_names_hash_bucket_size: 64

Have you seen this before?

Sorry for the delayed reply, I’ve been away for a while. In case you still have this issue (or for others who find this thread):

I haven’t seen this before, but some searching tells me that it’s to do with domain name length (someone else had the same problem - github issue here. In a regular nginx install you can update the http.conf file with the suggested line server_names_hash_bucket_size 64;

For Kobodocker, the nginx configs are generated using the files inside /path/to/kobo/nginx/. So, inside the nginx_site_https.conf.tmpl file, add the line server_names_hash_bucket_size 64; just below the charset utf8; line. Hopefully, when you restart the kobo docker, the nginx config will be updated and will load ok.

Let me know how it goes,
~ D.

1 Like


Yes, that was the issue. Looks like it’s up & running. Thanks so much for your time and insight.

1 Like

I renewed certs by following instructions above, however when I visit the site, I receive the following:
This certificate has expired or is not yet valid and it gives an expiration date of June 5th. Also it’s telling us that the site is not secure. Any help is greatly appreciated.