15/03/2025: updated for Kamal 2.

Introduction

Kamal is a developer tool that allows you to deploy a Docker application to a cloud VM from your command line.

Today I'll show you step by step how to deploy a Docker application (in my case a Django application) to a VPS on Contabo. Most of the blog posts and articles talk about Hetzner Cloud, but Contabo is as reliable and cheap.

So, first of all we spin off our Cloud VPS instance on Ubuntu; I chosed the 24.04 version.

Secure your VPS

Looking around the web, I found a very useful Ansible playbook to automatically optimize and secure your servers for Kamal (Ubuntu only):

https://github.com/guillaumebriday/kamal-ansible-manager

This script will automatically configure your server with packages to secure it:

• Fail2ban
• UFW
• NTP

The playbook also:

• Install Docker
• Remove Snap
• Disable ssh password login.

To run this script, first install Ansible according to the official documentation.

Prepare the server for Kamal

Before entering in the kamal stuff, there are some more things that need to be done in the server.

First, to avoid the error "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock", according to this blog post, you need to create the docker group (if it doesn't exist) and add your user to the docker group:

sudo groupadd docker
sudo usermod -aG docker ${USER}

and then verify that you can run docker commands:

docker run hello-world

With version 2, there is no more need to create a docker private network for Kamal to work (it's created automatically).

If you use Cloudflare, it's also important to verify your SSL settings. My settings were on "Flexible", and I wasn't able to access the web app, I was getting too many redirections. Setting it to Full, solved the problem:

In the host machine, be sure that you can login to your registry in order to Kamal publish and retrieve the Docker image. I'm using Github, for this you need to define a token with packages read/write permission. Once defined a token (CR_PAT for example), export it as an environment variable and check that:

export CR_PAT=<token_value>
echo $CR_PAT | docker login ghcr.io -u <username> --password-stdin

the registry login is successful.

Deploy your app with Kamal

When everything is fine, go to your project directory and type:

kamal init

This will create a config/deploy.yml file in your project folder. This is mine, now updated to Kamal version 2 which comes with kamal proxy:

Before deploying your app, boot the accessories with:

kamal accessory boot all

And for the application run:

kamal deploy

A very useful post on the same topic can be found here, but may be isn't updated for Kamal version 2.

Thomas