Deployment with Kamal¶

If you want to take full control over the deployment process and a server managed by yourself, you can use Kamal.

Prerequisites¶

Info

For simplicity purposes, this tutorial assumes you will use the root user to deploy the application.

Have your own server with SSH access. Read here if you are not using the root user.
Point your domain to your server's IP address, e.g.:

Record Type Host / Hostname / Name Value / Content / Alias of

A @ your-server-ip
On your local machine, install Kamal and make sure Docker is running.
Attention

Either
- copy the deploy/kamal.yml file to config/deploy.yml (the Kamal default directory config clashes with the config folder here, so this location is somewhat unfortunate)
- or append -c deploy/kamal.yml to every kamal command.

Change the following in the deploy.yml file:

service: my-app to the name of your application
image: my-user/my-app to your Docker Hub username and the name of the image you want to use
servers.web.[] to your server's IP address
proxy.host to the domain you want to use
registry.username to your Docker Hub username
builder.arch to the architecture of your server
env.secret add or remove secrets here so that all necessary secrets for your application are referenced here. The actual way to get the values is defined in the .kamal/secrets file, DjipFast uses Option 1: Read secrets from the environment.

Here is an example deploy.yml file with above changes highlighted

# Name of your application. Used to uniquely configure containers.
service: my-app

# Name of the container image.
image: my-user/my-app

# Deploy to these servers.
servers:
  web:
    - 192.168.0.1

# Enable SSL auto certification via Let's Encrypt and allow for multiple apps on a single web server.
# Remove this section when using multiple web servers and ensure you terminate SSL at your load balancer.
#
# Note: If using Cloudflare, set encryption mode in SSL/TLS setting to "Full" to enable CF-to-app encryption.
proxy:
  ssl: true
  host: app.example.com
  app_port: 8000
  healthcheck:
    interval: 3
    path: /up/
    timeout: 60

# Credentials for your image host.
registry:
  # Specify the registry server, if you're not using Docker Hub
  # server: registry.digitalocean.com / ghcr.io / ...
  username: my-user

  # Always use an access token rather than real password (pulled from .kamal/secrets).
  password:
    - KAMAL_REGISTRY_PASSWORD

# Configure builder setup.
builder:
  arch: arm64
  # Setting the current directory as context. Otherwise Kamal will only build files you have committed to your Git repository
  context: .

# Inject ENV variables into containers (secrets come from .kamal/secrets).
#
env:
  clear:
    DEBUG: False
  secret:
    - SECRET_KEY
    - SOCIAL_AUTH_GOOGLE_OAUTH2_KEY
    - SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET
    - EMAIL_HOST_PASSWORD
    - STRIPE_PUBLIC_KEY
    - STRIPE_SECRET_KEY
    - STRIPE_WEBHOOK_SECRET
    - GOOGLE_ANALYTICS_MEASUREMENT_ID
    - CRISP_WEBSITE_ID
    - SENTRY_DSN

# Use a different ssh user than root
#
# ssh:
#   user: app

# Use a persistent storage volume.
#
volumes:
  - /data:/code/data

Here is an example .kamal/secrets file

# Secrets defined here are available for reference under registry/password, env/secret, builder/secrets,
# and accessories/*/env/secret in config/deploy.yml. All secrets should be pulled from either
# password manager, ENV, or a file. DO NOT ENTER RAW CREDENTIALS HERE! This file needs to be safe for git.

# Option 1: Read secrets from the environment
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

SECRET_KEY=$SECRET_KEY

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=$SOCIAL_AUTH_GOOGLE_OAUTH2_KEY
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=$SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET

EMAIL_HOST_PASSWORD=$EMAIL_HOST_PASSWORD

STRIPE_PUBLIC_KEY=$STRIPE_PUBLIC_KEY
STRIPE_SECRET_KEY=$STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET=$STRIPE_WEBHOOK_SECRET

GOOGLE_ANALYTICS_MEASUREMENT_ID=$GOOGLE_ANALYTICS_MEASUREMENT_ID

CRISP_WEBSITE_ID=$CRISP_WEBSITE_ID

SENTRY_DSN=$SENTRY_DSN

# Option 2: Read secrets via a command
# RAILS_MASTER_KEY=$(cat config/master.key)

# Option 3: Read secrets via kamal secrets helpers
# These will handle logging in and fetching the secrets in as few calls as possible
# There are adapters for 1Password, LastPass + Bitwarden
#
# SECRETS=$(kamal secrets fetch --adapter 1password --account my-account --from MyVault/MyItem KAMAL_REGISTRY_PASSWORD RAILS_MASTER_KEY)
# KAMAL_REGISTRY_PASSWORD=$(kamal secrets extract KAMAL_REGISTRY_PASSWORD $SECRETS)
# RAILS_MASTER_KEY=$(kamal secrets extract RAILS_MASTER_KEY $SECRETS)

The KAMAL_REGISTRY_PASSWORD is a PAT (Personal Access Token) for your Docker Hub account. You can create one here. By default, Docker Hub creates public repositories. To avoid making your images public, set up a private repository before deploying, or change the default repository privacy settings to private in your Docker Hub settings.
Optional: Only required when using media uploads (e.g. when using the blog feature with images).
Serve uploaded files directly through Django

We need to make sure that files in the MEDIA_ROOT directory are served through Kamal. Since we're not using a dedicated web server like nginx for serving media files, we'll serve uploaded files directly through Django. While this is less efficient than using a proper web server or cloud storage solution, it's perfectly adequate for serving blog post images and similar low-traffic media content. Add the following highlighted lines to your config/urls.py file:
config/urls.py
```
# ...
from django.urls import include, path
from django.views.static import serve

urlpatterns = [
    # ...
    # sitemap
    path('sitemap.xml', sitemap, {'sitemaps': sitemaps}, name='django.contrib.sitemaps.views.sitemap'),
    # media
    path('media/<path:path>', serve, {'document_root': settings.MEDIA_ROOT}),
]
```
The environment variables defined in the first step need to be loaded before running the deployment. It is best to define a production .env.prod file, where all production related variables are set, including DEBUG=FALSE. This way you you have a clean separation between local development and production deployment. For the initial server setup and application deployment run the following:
```
dotenv -f ".env.prod" kamal setup
```
Attention

If you are using something like direnv, variables from a .env file are already loaded - and take precedence over the .env.prod file, even if you run dotenv -f ".env.prod" as prefix.
For subsequent deployments/updates, run:
```
dotenv -f ".env.prod" kamal deploy
```