Dokku is a wonderful Self-hosted PaaS service. It makes it trivial to run and manage custom applications on a cheap VPS machine hosted on providers like Digital Ocean, Hetzner and more. However, I could not find a tutorial for a simple use case: if we have an already existing docker image (e.g. on Docker hub), how do we run it on Dokku? This tutorial will explain how to host and deploy a docker image as a dokku application.
For this example, I’ll configure Shaarli, a simple PHP bookmarking service that is a great tool for sharing bookmarks between multiple devices. A self-hosted alternative to Pocket, or a throwback to Delicious (if you’re that old!).
This guide assumes that you already have dokku installed on the host machine. If you haven’t done it, please do. I recommend the official installation guide.
If you want to run a WordPress site, don’t forget to check out my tutorial on How to install WordPress with dokku.
Creating the dokku app from a docker image
Creating the app is as simple as dokku apps:create <app-name>.
Next, we need to configure the new application to use the preexisting docker image. In this case, I will use Shaarli, which is hosted in Github’s repository. If you need to access a private repo, don’t forget to run docker login.
dokku apps:create shaarli-app
# Run docker login, if needed
dokku git:from-image shaarli-app ghcr.io/shaarli/shaarli:release
This is a regular dokku app, so you can configure it using environment variables, link it to databases, check the app logs, etc!
Configuring docker volumes
For sure, you will want to persist data between restarts. The best way to achieve this with Dokku is to mount a docker volume to the container.
First, we create the docker volume, then we mount it to the application and lastly, we restart the application so the changes take effect. You can repeat this to as many volumes as needed.
The Dokku documentation explain in create detail how to manage volumes.
docker volume create shaarli-app-data
dokku storage:mount shaarli-app shaarli-app-data:/var/www/shaarli/data
dokku ps:restart shaarli-appSetting up the application domain
The last step is to make our application accessible using a domain, especially using HTTPS.
dokku domains:add shaarli-app example.com
# Install plugin
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
# Set the global email
dokku config:set --global [email protected]
# Setup cronjob to auto-renew certificates when they expire
dokku letsencrypt:cron-job --add
dokku letsencrypt:enable shaarli-appTIP: don’t forget to set up the DNS records to point to your server.
This step is very simples, we configure the domain that the application will use, and then enable HTTPS using dokku’s letsencrypt plugin.
Conclusion
Running a docker image on dokku is super simple. In a few minutes, you can be up and running, without much friction. I hope this tutorial was easy to follow along, and let me know if you have any questions!
Leave a Reply