BookWyrm is a federated social reading platform built on ActivityPub. It runs as a Django/Gunicorn application and requires a web server in front of it to serve static files correctly.

Gunicorn does not serve static files. Without nginx in front of it, requests for CSS, JavaScript, and images return an HTML error page with the wrong MIME type, breaking the entire UI. Browsers enforce X-Content-Type-Options: nosniff and block the resources entirely.

nginx must sit between your reverse proxy and Gunicorn and handle /static/ and /images/ directly from the Docker volumes.

The right setup depends on whether you are using the official BookWyrm docker-compose or integrating BookWyrm into your own existing stack.

• Official docker-compose with Cloudflare Tunnel – Clone the BookWyrm repo and use their bundled compose file. nginx and certbot are already included. This is the recommended path for new installs.
• Custom stack with Caddy – Add BookWyrm services to an existing compose stack. nginx is added manually. Caddy handles TLS.

On first start, BookWyrm runs database migrations and collects static assets automatically. After the web (or bookwyrm-web) container is healthy, run:

```bash docker compose exec web python manage.py admin_code ```

This outputs a one-time code. Visit https://books.example.com/setup and enter it to create your admin account and configure the instance.

The celery-beat container imports all of BookWyrm's Django settings, including EMAIL_HOST. This variable is required even though the beat scheduler never sends email. Omitting it causes the container to crash on startup with:

``` ValueError: Couldn't import 'celerywyrm': Environment variable “EMAIL_HOST” not set ```

Pass the full email environment block to celery-beat, the same as for the web container.

• BookWyrm Production Install
• BookWyrm on GitHub

• BookWyrm with Caddy
• BookWyrm with Cloudflare Tunnel
• Docker Compose

Last updated: 2026-06-21

• Return to Docker