dsd-vps-kamal

A django-simple-deploy plugin for deploying Django projects to any VPS using Kamal.

Hetzner, DigitalOcean, Linode et al. — if you can SSH into it, you can deploy to it.

• Current Status 🙋‍♂️
• Installation 💻
• Configuration-only mode
• Fully automated deployment ⚡
• Options
  • --ip-address (required)
  • --host (required for HTTPS, optional otherwise)
  • --sqlite (optional)
• Installing Kamal 🔧
• Development 🛠️
• Special Thanks ❤️
• License 📄

Current Status 🙋‍♂️

This plugin is in a pre-1.0 development phase. It's ready for use, but the API is not yet stable. See the roadmap to v1 for what's planned.

Installation 💻

pip install dsd-vps-kamal

Then add django_simple_deploy to INSTALLED_APPS in your settings.py:

INSTALLED_APPS = [
    # ...
    "django_simple_deploy",
]

Usage 🧑‍🔧

Configuration-only mode

By default, the plugin configures your project for deployment but doesn't actually deploy. You review the changes, commit, and deploy yourself:

python manage.py deploy --ip-address <your-vps-ip>

This generates all the files Kamal needs — deploy.yml, Dockerfile, secrets, and production settings. Review the changes, then:

git add .
git commit -m "Configured for deployment via Kamal."
rvx kamal setup # see »Installing Kamal« below for more details

Fully automated deployment ⚡

Pass --automate-all and the plugin handles everything — configuration, committing, and running kamal setup for you:

python manage.py deploy --automate-all --ip-address <your-vps-ip>

This requires a few things to be in place:

• VPS provisioning is out of scope (for now) — bring your own server; this command does not create or configure the VPS itself yet.
• SSH root access — ssh root@<your-vps-ip> must work without a password prompt
• Docker running locally — the Docker daemon needs to be active on your machine. We recommend Docker Desktop.
• Kamal installed locally — see Installing Kamal below

Options

--ip-address (required)

The IPv4 address of your VPS. This is how the plugin knows where to deploy.

--host (required for HTTPS, optional otherwise)

A domain name for Kamal's proxy routing, e.g. myapp.example.com. If you've pointed a DNS record at your VPS, pass it here:

python manage.py deploy --ip-address <your-vps-ip> --host myapp.example.com

If omitted, your app is served over HTTP on the IP address (no automatic TLS certificate).

--sqlite (optional)

Use SQLite instead of PostgreSQL:

python manage.py deploy --ip-address <your-vps-ip> --sqlite

Uses dj-lite for production-ready SQLite by default.

Installing Kamal 🔧

Kamal is a Ruby gem. If you already have Ruby set up:

gem install kamal

If you'd rather not manage a Ruby environment, we recommend rv:

brew install rv  # see https://github.com/spinel-coop/rv#installation for other OSes
rv tool install kamal

Then use rvx kamal wherever you'd normally run kamal. The plugin detects rv automatically when using --automate-all.

Development 🛠️

Install Just to run the development commands:

just dev-setup  # clones core + installs everything in editable mode

## Other `just` recipes for development:
    lint             # Check linting (no fixes)
    format           # Format code
    test-unit        # Run unit tests
    test-integration # Run integration tests

All available just commands:

just --list

Special Thanks ❤️

• Eric Matthes for django-simple-deploy — making Django deployment accessible to everyone
• David Heinemeier Hansson for Kamal — zero-downtime deployments to any VPS without the complexity
• Jeff Triplett for django-startproject — a fantastic project template and inspiration
• Adam Hill for dj-lite — production-ready SQLite for Django
• The Djangonauts program & Team Venus 🪐 - Session 6

License 📄

BSD 3-Clause © Jan Raasch