How to build docker image locally and deploy to dokku host

Dokku has become one of my favorite softwares for deploying applications. That's because hosting applications can be tedious or very expensive, and thankfully Dokku solves both. With a low budget VPS you could host multiple applications (for example, for experimenting with a new stack or software or publish your own portafolio) thanks to Docker and nginx.

Software development tools have become resource-heavy and they just don't run well on limited hardware. For example, I love payload project but even in a machine from 2020 it was difficult to develop a payload based application because of the slowness on compilation. This blog itself is built on payload and published on a low budget VPS running dokku, and I faced some problems while publishing a new update to my blog app.

The whys not to build docker images on dokku host:

1. You don't have lot of resources in you dokku host and when deploying, it freezes.
2. You want a faster compilation of the image than in the dokku host.
3. You just don't want to do it there.

It doesn't matter your reason, let's do it.

Prerequisites

1. Available and configured dokku (0.30.0+) host.
2. Already configured app in dokku (domains, ports, etc).
3. Local machine with Docker installed. (Docker Desktop needed if your host platform doesn't match your PC platform i.e. amd64 on host and arm64 in PC. Why?)
4. Source code ready for compilation (Dockerfile).
5. SSH access to dokku host.

TLDR

1# --- In your PC ---
2
3# Build the image
4docker build -t <your_app_name>:<tag> .
5# Use this command instead if cross compiling to other platforms (Docker Desktop needed)
6docker buildx build -t <your_app_name>:<tag> . --platform linux/amd64,linux/arm64
7# Transfer the image
8docker image save <your_app_name>:<tag> --platform linux/amd64 | ssh user@yourdokkuhost.com docker load
9
10# --- In the dokku host ---
11
12# Only if the image name changes
13dokku git:from-image <your_app_name>:<tag>
14# If want to reflect the changes to the app (redeploying)
15dokku ps:rebuild payload
shell

Steps

1. Build docker image from Dockerfile

Open your favorite shell, change directory to your app source code and build you application docker image using the command below.

1docker build -t <your_app_name>:<tag> .
2# i.e docker build -t my-blog:latest .
shell

If your host platform doesnt match the one you have in your PC, please use this command. Specify the platforms you want to build the image to. In the example below, I build the image for amd64 (for my dokku host) and arm64 (for my PC)

1docker buildx build -t <your_app_name>:<tag> . --platform linux/amd64,linux/arm64
shell

2. Save docker image to host

Once your image is built, you can deploy the image using docker image save (saves to sdtout) and send it to via ssh to dokku host. Platform flag is not necessary if the platform is the same, but in this case, I want to publish the image for platform amd64 to the host.

1docker image save <your_app_name>:<tag> --platform linux/amd64 | ssh user@yourdokkuhost.com docker load
shell

3. Deploy image to Dokku app

After the image is transferred, open a new SSH connection to your dokku host, and confirm the image it is now on the host repository (using docker image ls). Once confirmed, you need to instruct Dokku to use that image for your app, and that is only needed the first time if you don't change the name of your image (e.g from my-blog to my-awesome-blog-image), otherwise, it will be needed too.

1# Make sure to execute this in the dokku host
2dokku git:from-image <your_app_name>:<tag>
shell

For any subsequent pushes of the image, you need to run the following command in order to take effect.

1dokku ps:rebuild payload
shell

After this last command you can see an output something like this:

1-----> Checking for postdeploy task
2       No postdeploy task found, skipping
3-----> Updated schedule file
4-----> Shutting down old containers in 60 seconds
5=====> Application deployed:
6       http://ernestorb.com
shell

Conclusion

Deploying docker images built in our local machine can be done easily thanks to both docker and dokku utilities. After this, you should now enjoy with more fast deploys and stop oversaturating your dokku host.