`, and `~/app` points at the live one. Data
lives in `~/data`. nginx (user `www-data`) serves static files and
uploads, so it may pass through your home directory without listing it;
the database stays private to `exedev`.
```bash
chmod 711 ~
mkdir -p ~/releases ~/app-settings ~/.local/bin
install -d -m 711 ~/data
install -d -m 755 ~/data/media
[ -e ~/data/db.sqlite3 ] || install -m 600 /dev/null ~/data/db.sqlite3
uv --version
```
uv comes with the VM. It installs the Python version your project asks
for (in `.python-version` or `requires-python`) the first time you deploy.
### Get your code
Pick one. Both leave a git checkout in `~/seed`, which the first deploy
pushes from.
#### Bring your repository
Set `REPO` to your repository and clone it. Public repositories clone
over HTTPS:
```bash
REPO=owner/name
slug=$(echo "$REPO" | sed -E 's#^(https://github\.com/|git@github\.com:)##; s#\.git$##; s#/$##')
git clone "https://github.com/$slug.git" ~/seed
```
For a **private** repository, connect it with the
[GitHub integration](/docs/integrations-github) instead, so no token
lands on the VM. On your computer:
```bash
ssh exe.dev integrations add github --name my-django-repo --repository owner/name --attach vm:my-django
```
Then clone through the integration, on the VM:
```bash
git clone "https://github.int.exe.xyz/$slug.git" ~/seed
```
The deploy hook expects `manage.py` at the top of the repository, and
either `uv.lock`, `requirements.txt`, or a `pyproject.toml` with a
`[project]` table. uv picks the Python version from `.python-version`,
`requires-python`, or Heroku's `runtime.txt`. Check:
```bash
cd ~/seed && ls -A | grep -xE 'manage.py|uv.lock|requirements.txt|pyproject.toml|.python-version|runtime.txt'
```
The app gets a fresh SQLite database. To bring data from another
database, run `manage dumpdata` there and `manage loaddata` here after
the first deploy.
#### Start a new project
Create a project with uv and `django-admin startproject`, add a home
page, and commit:
```bash
mkdir ~/seed && cd ~/seed
uv init --quiet --no-package --python 3.14 --name mysite
rm main.py
uv add --quiet 'django~=6.1.0' gunicorn
uv run django-admin startproject mysite .
mkdir templates
sed -i "s|'DIRS': \[\],|'DIRS': [BASE_DIR / 'templates'],|" mysite/settings.py
printf '%s\n' db.sqlite3 /staticfiles/ /media/ >> .gitignore
```
The home page, and a short README:
```bash
cd ~/seed
cat > mysite/urls.py <<'EOF'
from django.contrib import admin
from django.urls import path
from django.views.generic import TemplateView
urlpatterns = [
path("", TemplateView.as_view(template_name="home.html"), name="home"),
path("admin/", admin.site.urls),
]
EOF
cat > templates/home.html <<'EOF'
mysite
Hello from Django
{% if user.is_authenticated %}
You're signed in as {{ user.get_username }}.
{% else %}
You're not signed in to this app.
{% endif %}
Edit templates/home.html, commit, and run
git push exe main. The admin
is ready.
EOF
cat > README.md <<'EOF'
# mysite
Run it locally:
uv run manage.py migrate
uv run manage.py runserver
Deploy: `git push exe main`
EOF
uv run manage.py check
```
Expect `System check identified no issues`. Commit, as the VM's owner:
```bash
cd ~/seed
email=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r .email)
git add .gitignore .python-version README.md manage.py mysite pyproject.toml templates uv.lock
git -c user.name="$email" -c user.email="$email" commit --quiet -m "New Django project"
git log --oneline
```
### Production settings
The VM's settings live outside your repository. `~/app.env` holds the
secrets and per-server values; systemd and the deploy hook both read it,
so keep to `KEY=value` lines without quotes or spaces. This finds your
project's settings module and WSGI application, then writes the file
once, with a new secret key:
```bash
cd ~/seed
settings=$(sed -n "s/.*DJANGO_SETTINGS_MODULE['\"], *['\"]\([^'\"]*\)['\"].*/\1/p" manage.py | head -n 1)
wsgi=$(grep -rhoP --include='*.py' "^WSGI_APPLICATION\s*=\s*['\"]\K[^'\"]+" . | head -n 1)
wsgi="${wsgi%.*}:${wsgi##*.}"
echo "settings: $settings wsgi: $wsgi"
if [ ! -e ~/app.env ]; then
install -m 600 /dev/null ~/app.env
cat >> ~/app.env < ~/app-settings/exe_settings.py <<'EOF'
"""Production settings for this exe.dev VM.
Loads the project's settings (PROJECT_SETTINGS in ~/app.env), then sets
what the server decides. The repository doesn't change, and runserver on
your computer keeps using the project's own settings.
"""
import os
from importlib import import_module
from pathlib import Path
import django
_project = import_module(os.environ["PROJECT_SETTINGS"])
globals().update({k: v for k, v in vars(_project).items() if k.isupper()})
DATA = Path.home() / "data"
DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
# exe.dev's proxy ends TLS and forwards the request with the original Host
# and X-Forwarded-Proto: https. Without SECURE_PROXY_SSL_HEADER, Django
# thinks every request is plain HTTP: forms fail with "CSRF verification
# failed. Origin checking failed", and absolute URLs start with http://.
ALLOWED_HOSTS = os.environ["DJANGO_ALLOWED_HOSTS"].split(",")
CSRF_TRUSTED_ORIGINS = [f"https://{host}" for host in ALLOWED_HOSTS]
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
# exe.dev already redirects http:// to https:// and sends HSTS, so
# SECURE_SSL_REDIRECT and SECURE_HSTS_SECONDS would only repeat it.
SILENCED_SYSTEM_CHECKS = [
*globals().get("SILENCED_SYSTEM_CHECKS", []),
"security.W004",
"security.W008",
]
# SQLite on the persistent disk, set up for a web server.
DATABASES = {
"default": {
"ENGINE": "django.db.backends.sqlite3",
"NAME": DATA / "db.sqlite3",
"CONN_MAX_AGE": 600,
"OPTIONS": {
# Take the write lock when a transaction starts, so concurrent
# writers wait their turn instead of failing with "database is
# locked"; wait up to 5 seconds for it.
"transaction_mode": "IMMEDIATE",
"timeout": 5,
"init_command": (
"PRAGMA journal_mode=WAL;" # readers don't block the writer
"PRAGMA synchronous=NORMAL;" # safe with WAL, and faster
"PRAGMA mmap_size=134217728;" # read through 128 MB of mmap
"PRAGMA journal_size_limit=27103364;" # trim the WAL file
"PRAGMA cache_size=2000;"
),
},
}
}
# nginx serves both from disk. STATIC_ROOT is inside the release being
# built or run: the deploy hook and app.service run there.
STATIC_URL = "/static/"
STATIC_ROOT = Path.cwd() / "staticfiles"
MEDIA_URL = "/media/"
MEDIA_ROOT = DATA / "media"
# A STORAGES setting that only names the static files storage leaves
# uploads without one; store them on disk, in MEDIA_ROOT.
if "STORAGES" in globals() and "default" not in STORAGES:
STORAGES = {
**STORAGES,
"default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
}
# With DEBUG off, Django's default logging prints nothing; send warnings
# and errors, with tracebacks, to the journal: journalctl -u app.
if "LOGGING" not in globals():
LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {"console": {"class": "logging.StreamHandler"}},
"root": {"handlers": ["console"], "level": "WARNING"},
}
# Email goes through exe.dev's gateway (exe_mail.py), unless the project
# already sends real email: Django's development backends only print it.
# Django emails ADMINS a traceback when a page fails with a server error.
_dev_mail = {
f"django.core.mail.backends.{name}.EmailBackend"
for name in ("console", "dummy", "filebased", "locmem")
}
if "MAILERS" in globals(): # Django 6.1 and later
if MAILERS.get("default", {}).get("BACKEND") in _dev_mail:
MAILERS = {**MAILERS, "default": {"BACKEND": "exe_mail.EmailBackend"}}
elif globals().get("EMAIL_BACKEND") in _dev_mail or not {"EMAIL_BACKEND", "EMAIL_HOST"} & globals().keys():
EMAIL_BACKEND = "exe_mail.EmailBackend"
if not globals().get("ADMINS") and os.environ.get("DJANGO_ADMINS"):
_admins = os.environ["DJANGO_ADMINS"].split(",")
# Django 6.0 takes addresses; older versions take (name, address).
ADMINS = _admins if django.VERSION >= (6, 0) else [(a, a) for a in _admins]
# Sign visitors in with their exe.dev account; see exe_login.py.
_auth = "django.contrib.auth.middleware.AuthenticationMiddleware"
if _auth in MIDDLEWARE:
MIDDLEWARE = list(MIDDLEWARE)
MIDDLEWARE.insert(MIDDLEWARE.index(_auth) + 1, "exe_login.ExeDevLoginMiddleware")
AUTHENTICATION_BACKENDS = [
"exe_login.ExeDevBackend",
*globals().get("AUTHENTICATION_BACKENDS", ["django.contrib.auth.backends.ModelBackend"]),
]
EOF
```
The exe.dev login, using Django's own `RemoteUserMiddleware` with
exe.dev's header:
```bash
cat > ~/app-settings/exe_login.py <<'EOF'
"""Sign visitors in with their exe.dev account.
exe.dev's proxy adds X-ExeDev-Email to requests from visitors who have
signed in to exe.dev on this site (https://exe.dev/docs/login-with-exe;
public sites: /__exe.dev/login?redirect=/admin/). This signs
them in as the Django user whose username is that email address, and
signs them out when the header goes away.
"""
from django.contrib.auth.backends import RemoteUserBackend
from django.contrib.auth.middleware import RemoteUserMiddleware
class ExeDevLoginMiddleware(RemoteUserMiddleware):
header = "HTTP_X_EXEDEV_EMAIL"
class ExeDevBackend(RemoteUserBackend):
# False: only people who already have a user are signed in.
# True: everyone who can open the site gets a user, with no
# permissions until you grant some in the admin.
create_unknown_user = False
def clean_username(self, username):
return username.strip().lower()
def configure_user(self, request, user, created=True):
if created and hasattr(user, "email"):
user.email = user.get_username()
user.save(update_fields=["email"])
return user
EOF
```
And email, through the VM's [email gateway](/docs/send-email):
```bash
cat > ~/app-settings/exe_mail.py <<'EOF'
"""Send Django's email through exe.dev's email gateway.
Plain text and attachments, to the VM's owner, its team, and people it's
shared with who have signed in (https://exe.dev/docs/send-email); the
gateway refuses other addresses. To email anyone, configure an email
provider in your project's settings; exe_settings.py then leaves it be.
"""
import base64
import json
import urllib.error
import urllib.request
from django.core.mail.backends.base import BaseEmailBackend
GATEWAY = "http://169.254.169.254/gateway/email/send"
class EmailBackend(BaseEmailBackend):
def __init__(self, fail_silently=False, **kwargs):
super().__init__(**kwargs)
self.fail_silently = fail_silently
def send_messages(self, email_messages):
sent = 0
for message in email_messages:
try:
for to in message.recipients():
self.send(message, to)
sent += 1
except Exception:
if not self.fail_silently:
raise
return sent
def send(self, message, to):
data = {"to": to, "subject": message.subject, "body": message.body}
if message.reply_to:
data["reply_to"] = message.reply_to[0]
files = [a for a in message.attachments if isinstance(a, tuple)]
if files:
data["attachments"] = [
{
"filename": name,
"content": base64.b64encode(
content.encode() if isinstance(content, str) else content
).decode(),
"content_type": mimetype or "application/octet-stream",
}
for name, content, mimetype in files
]
request = urllib.request.Request(
GATEWAY, json.dumps(data).encode(), {"Content-Type": "application/json"}
)
try:
urllib.request.urlopen(request, timeout=10).close()
except urllib.error.HTTPError as e: # e.g. 403 for other addresses
error = e.read().decode(errors="replace")
raise OSError(f"exe.dev email to {to}: {error}") from e
EOF
```
### The deploy hook
`~/app.git` is the repository you push to. Its `pre-receive` hook builds
each push to `main` as a new release before git accepts it: it installs
dependencies with uv, runs `check --deploy`, `migrate`, and
`collectstatic`, loads the app, then points `~/app` at the release,
restarts, and checks that the site answers. If any step fails, git
rejects the push and the previous release keeps running (or is put back,
if the new one fails after the switch).
```bash
git init --quiet --bare ~/app.git
cat > ~/app.git/hooks/pre-receive <<'EOF'
#!/usr/bin/env bash
# Deploy pushes to main: build a new release in ~/releases, migrate,
# collect static files, switch ~/app to it, restart, and check it
# answers. Any failure rejects the push; the running release stays.
set -euo pipefail
umask 022
exec 9>"$HOME/.deploy.lock" && flock 9
new=
while read -r _old sha ref; do
if [ "$ref" = refs/heads/main ]; then new=$sha; fi
done
if [ -z "$new" ]; then echo "Only pushes to main deploy."; exit 0; fi
if [ "$new" = 0000000000000000000000000000000000000000 ]; then
echo "Refusing to delete main."; exit 1
fi
rel="$HOME/releases/$(date -u +%Y%m%d-%H%M%S)-${new:0:7}"
prev=$(readlink "$HOME/app" || true)
# Remove the new release unless it ended up live.
trap '[ "$(readlink -f "$HOME/app")" = "$rel" ] || rm -rf "$rel"' EXIT
echo "-----> Building ${new:0:7}"
mkdir -p "$rel"
git archive "$new" | tar -x -C "$rel"
# Leave git's push environment behind before running the build.
unset GIT_DIR GIT_QUARANTINE_PATH GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
set -a; . "$HOME/app.env"; set +a
cd "$rel"
if [ -f uv.lock ]; then
uv sync --locked --no-dev
elif [ -f requirements.txt ]; then
py=
if [ ! -f .python-version ] && [ -f runtime.txt ]; then
# Heroku's runtime.txt: python-3.12.4 means Python 3.12.
py=$(sed -n 's/^python-\([0-9]*\.[0-9]*\).*/\1/p' runtime.txt)
fi
uv venv --quiet ${py:+--python "$py"}
uv pip install -r requirements.txt
else
uv sync --no-dev
fi
uv pip install --quiet gunicorn # does nothing if the project has it
echo "-----> Checking, migrating, collecting static files"
.venv/bin/python manage.py check --deploy
.venv/bin/python manage.py migrate --noinput
.venv/bin/python manage.py collectstatic --noinput --verbosity 0
# Load the app the way gunicorn will, so startup errors stop here.
.venv/bin/python -c 'import os, gunicorn.util; gunicorn.util.import_app(os.environ["WSGI_APP"])'
switch() { ln -sfn "$1" "$HOME/app.new" && mv -T "$HOME/app.new" "$HOME/app"; }
restart() {
sudo systemctl restart app
if systemctl is-enabled --quiet app-worker 2>/dev/null; then sudo systemctl restart app-worker; fi
}
echo "-----> Starting ${new:0:7}"
switch "$rel"
restart
for _ in $(seq 30); do
code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/ || true)
case "$code" in [1234]??|500) break ;; esac
# Stop waiting once gunicorn has crashed and systemd restarted it.
[ "$(systemctl show app -p NRestarts --value)" = 0 ] || break
sleep 1
done
case "$code" in
[1234]??) ;;
*)
echo "-----> The new release answered HTTP $code. Logs:"
journalctl -u app -n 40 -o cat --no-pager || true
if [ -n "$prev" ]; then echo "-----> Going back to $prev"; switch "$prev"; restart; fi
exit 1 ;;
esac
# Keep the five newest releases.
ls -1d "$HOME"/releases/*/ | sort | head -n -5 | xargs -r rm -rf
echo "-----> Deployed ${new:0:7}: https://$(hostname).exe.xyz/"
EOF
chmod +x ~/app.git/hooks/pre-receive
```
`manage` runs `manage.py` in the live release with the server's
settings, from any directory:
```bash
cat > ~/.local/bin/manage <<'EOF'
#!/bin/sh
# manage : Django's manage.py for the live app, with its settings.
set -a; . "$HOME/app.env"; set +a
cd "$HOME/app" && exec .venv/bin/python manage.py "$@"
EOF
chmod +x ~/.local/bin/manage
```
### Run it with systemd and nginx
`app.service` runs gunicorn on `127.0.0.1:8001`, from whichever release
`~/app` points at, and restarts it if it stops:
```bash
sudo tee /etc/systemd/system/app.service >/dev/null <<'EOF'
[Unit]
Description=Django app (gunicorn)
After=network.target
[Service]
User=exedev
Group=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
ExecStart=/home/exedev/app/.venv/bin/gunicorn --bind 127.0.0.1:8001 --access-logfile - ${WSGI_APP}
Restart=always
RestartSec=2
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app
```
nginx listens on port 8000, where exe.dev's [HTTPS proxy](/docs/proxy)
sends traffic. It serves `/static/` and `/media/` from disk and passes
everything else to gunicorn, along with exe.dev's headers. It replaces
nginx's default site, which also uses port 8000.
```bash
sudo tee /etc/nginx/sites-available/app >/dev/null <<'EOF'
# exe.dev's proxy -> nginx :8000 -> gunicorn 127.0.0.1:8001.
# Files with a content hash in their name (ManifestStaticFilesStorage)
# never change, so browsers may cache them forever.
map $uri $static_expires {
"~\.[0-9a-f]{12}\.\w+$" max;
default off;
}
server {
listen 8000 default_server;
listen [::]:8000 default_server;
server_name _;
client_max_body_size 100m;
gzip_types text/css application/javascript application/json image/svg+xml;
location /static/ {
alias /home/exedev/app/staticfiles/;
expires $static_expires;
access_log off;
}
location /media/ {
alias /home/exedev/data/media/;
add_header X-Content-Type-Options nosniff;
}
location / {
proxy_pass http://127.0.0.1:8001;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header X-Forwarded-Host $http_x_forwarded_host;
proxy_set_header X-Forwarded-For $http_x_forwarded_for;
proxy_redirect off;
}
}
EOF
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -sf /etc/nginx/sites-available/app /etc/nginx/sites-enabled/app
sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx
```
Expect `syntax is ok` and `test is successful`. Until the first deploy,
`curl localhost:8000` returns 502: gunicorn isn't running yet.
### Deploy
Push the checkout to `~/app.git`. This is the same deploy a `git push`
from your computer runs; the first one also downloads Python if needed:
```bash
cd ~/seed && git push ~/app.git HEAD:main
```
It ends with `-----> Deployed`. Check the site, a static file, and the
admin login page:
```bash
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/static/admin/css/base.css
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/admin/login/
manage check --deploy
sqlite3 ~/data/db.sqlite3 'PRAGMA journal_mode'
```
Expect `200` for each (your own app's home page may redirect with `301`
or `302`, or answer `404` if it has none), `System check identified no issues`, and `wal`.
The checkout has done its job:
```bash
cd ~ && rm -rf ~/seed
```
### Create your admin user
Make the VM owner's exe.dev account a superuser. It has no password;
exe.dev's login signs you in:
```bash
email=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r .email)
manage createsuperuser --noinput --username "$email" --email "$email"
curl -s -o /dev/null -w '%{http_code}\n' -H "X-ExeDev-Email: $email" http://localhost:8000/admin/
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/admin/
```
Expect `200` with the header (signed in) and `302` without it (sent to
the login page). If your project's user model logs in by email rather
than username, use `--email "$email"` alone.
Check uploads, too: save a file through Django's storage and fetch it
from nginx:
```bash
manage shell -v 0 -c 'from django.core.files.base import ContentFile; from django.core.files.storage import default_storage as s; print(s.save("hello.txt", ContentFile(b"hello")))'
curl -s http://localhost:8000/media/hello.txt; echo
rm ~/data/media/hello.txt
```
Expect `hello.txt`, then `hello`.
### Set up nightly backups
`app-backup` takes a consistent copy of the database with SQLite's
backup command (copying a live database file with `cp` can catch it
half-written), checks it, and packs it with the uploads, `~/app.env`, the
settings, and a bundle of the git repository. It keeps seven.
```bash
cat > ~/.local/bin/app-backup <<'EOF'
#!/usr/bin/env bash
# Back up the Django app to ~/backups: the database, uploads, settings
# and secrets, and the git repository. Keeps the 7 newest.
set -euo pipefail
umask 077
mkdir -p "$HOME/backups"
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
sqlite3 "$HOME/data/db.sqlite3" ".backup '$work/db.sqlite3'"
test "$(sqlite3 "$work/db.sqlite3" 'PRAGMA integrity_check')" = ok
git -C "$HOME/app.git" bundle create --quiet "$work/app.bundle" --all
out="$HOME/backups/app-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" --exclude=__pycache__ \
-C "$work" db.sqlite3 app.bundle \
-C "$HOME" app.env app-settings \
-C "$HOME/data" media
mv "$out.part" "$out"
ls -1 "$HOME"/backups/app-*.tar.gz | sort | head -n -7 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/.local/bin/app-backup
```
Run it every night with a systemd timer, and take the first backup now:
```bash
sudo tee /etc/systemd/system/app-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up the Django app to ~/backups
[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/.local/bin/app-backup
EOF
sudo tee /etc/systemd/system/app-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the Django app nightly
[Timer]
OnCalendar=*-*-* 03:00:00
RandomizedDelaySec=30m
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-backup.timer
sudo systemctl start app-backup.service
systemctl list-timers app-backup.timer
ls -lh ~/backups
```
Check the newest backup in a scratch directory: the database passes an
integrity check, and the repository bundle has your commit.
```bash
latest=$(ls -1 ~/backups/app-*.tar.gz | sort | tail -n 1)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$latest" -C /tmp/restore-check
sqlite3 /tmp/restore-check/db.sqlite3 'PRAGMA integrity_check; SELECT count(*) FROM django_migrations;'
git -C /tmp/restore-check bundle list-heads app.bundle
rm -rf /tmp/restore-check
```
Expect `ok`, a number of migrations, and `refs/heads/main`. Setup is
done: everything is enabled to start at boot. Continue with
[Open your app](#open-your-app).