The Hidden Blog

As it turns out, I do have a hostname.

Deploying Docker images with Dokku and a custom nginx configuration

Published on Jul 21, 2024

I've recently switched to Dokku to deploy simple apps and projects on my server. It's an amazing open source tool and essentially a wrapper around Docker. This also means that if you uninstall Dokku all your containers would still just keep running in Docker. There's no lock-in.

Usually the Dokku workflow involves pushing a git branch to your server where it will then trigger a rebuild and redeploy of your code. You can also include custom nginx config files in your repository which makes it possible to deploy your code with a custom webserver configuration. This works well when you are deploying your own code, but isn't really possible when you want to deploy a ready-made Docker image that someone else created. If you are the author of a public Docker image you probably also don't want to bake in deployment specific files.

I ran into exactly this issue when I tried to deploy Miniflux via Dokku, where I wanted to have my custom nginx configuration while at the same time use the official Docker image.

After reading through the community forums I saw that someone had a similar question and the solution was to overwrite one of the hooks that Dokku has to inject a custom config from another location that's not the repository / image that you are deploying. I didn't know anything about Dokku but it's a Go project and it didn't seem too complicated.

The result is a new plugin github.com/dewey/dokku-nginx-override-by-app and the main objective is summarized in the README.

This plugin makes it possible to customize the nginx configuration for an app that is based on an existing Docker image. This is the case if you create a new app with the Dokku git:from-image command. For regular apps it's already possible to overwrite the nginx configuration by placing a nginx.conf.sigil file in the root of your code base, this won't work if you are using a third party image where you can't influence the code base. This is where this project comes in.

Just by putting files in a specific location Dokku will know to use that one during the deploy and your custom configuration is used. I'm using this plugin for all my projects, so if you have any questions or feedback do let me know or open an issue on GitHub.