build-wagtail

Dockerise a Wagtail project in place with one command. It generates a Dockerfile, settings overrides and a compose.yml, copies the site's database and media into ./data, and builds the image. The app runs on granian.

Needs Docker with the compose plugin. The tool itself has no dependencies.

Install

uv tool install build-wagtail   # or: pipx install build-wagtail

Usage

Run it from the Wagtail project root (where manage.py is):

build-wagtail example.org,www.example.org
docker compose up -d
docker compose exec web python manage.py createsuperuser

The first hostname is canonical. The site is served on 127.0.0.1:8000; put a reverse proxy in front of it for TLS. By default the host's proxy is expected to serve /static and /media from ./data, and the tool prints an example Caddy config for that. With --caddy, a Caddy container serves them instead.

The project needs a uv.lock, pyproject.toml or requirements.txt.

What it writes

• .env: secret key, hostnames and the container user. Created once, never overwritten.
• data/: the live database, media and collected static files. Seeded once, never overwritten. Back it up.
• .wagtail-docker/ and compose.yml: regenerated on every run. Options aren't stored, so pass the same ones each time.