feat: add optional letsencrypt tls

README.md

@@ -10,19 +10,21 @@ stores content, and Docker Compose supplies a reproducible local environment.
   aggregate read-only API at `GET /api/site/home/`.
 - `frontend/`: Astro components, responsive design system, typed API adapter, and
   Italian fallback content for development when the CMS is unavailable.
-- `nginx/`: reverse-proxy virtual host for `azionelab.org`, routing public requests to
-  Astro or Wagtail.
+- `nginx/`: reverse proxy for `azionelab.org`, with optional HTTPS termination and
+  automatic reload after certificate renewal.
+- `certbot/`: optional Let's Encrypt HTTP-01 issue/renew loop for direct deployments.
 - `db`: persistent PostgreSQL database.
-- Docker volumes: `postgres_data` for the database and `media_data` for uploads.
+- Docker volumes persist PostgreSQL, media, ACME challenges, and certificates.
 
 See [the architecture document](docs/architecture.md),
 [ADR-0001](docs/adr/0001-headless-wagtail-astro.md), and
-[ADR-0002](docs/adr/0002-nginx-reverse-proxy.md) for the rationale.
+[ADR-0002](docs/adr/0002-nginx-reverse-proxy.md), and
+[ADR-0003](docs/adr/0003-optional-letsencrypt.md) for the rationale.
 
 ## Prerequisites
 
 - Docker Engine with Docker Compose v2.
-- Ports `8080`, `4321`, and `8000` available on localhost.
+- Ports `8080`, `8443`, `4321`, and `8000` available on localhost.
 - A local hosts-file entry mapping `azionelab.org` to `127.0.0.1`.
 
 No host Python or Node.js installation is required.
@@ -53,7 +55,32 @@ Direct loopback ports `4321` and `8000` remain available for local diagnostics o
 
 The frontend remains usable with curated fallback content if the API is unavailable.
 On first startup the backend applies migrations and collects static files before
-starting Gunicorn. Wait until all four services report healthy.
+starting Gunicorn. Wait until the four default services report healthy. The optional
+`certbot` service has zero replicas while `LETSENCRYPT_ENABLED=0`.
+
+## Optional HTTPS with Let's Encrypt
+
+Keep `LETSENCRYPT_ENABLED=0` when a load balancer terminates TLS. For direct public
+exposure, first point the domain DNS records to the host and make TCP ports 80 and 443
+reachable, then set:
+
+```dotenv
+LETSENCRYPT_ENABLED=1
+LETSENCRYPT_DOMAIN=azionelab.org
+LETSENCRYPT_EMAIL=operator@example.org
+LETSENCRYPT_STAGING=1
+NGINX_BIND_ADDRESS=0.0.0.0
+NGINX_HTTP_PORT=80
+NGINX_HTTPS_PORT=443
+WAGTAILADMIN_BASE_URL=https://azionelab.org
+DJANGO_DEBUG=false
+```
+
+Start with the staging CA to validate DNS and firewall configuration without consuming
+production rate limits. Then change `LETSENCRYPT_STAGING=0` and remove the staging
+certificate volume before requesting the trusted certificate; staging certificates
+cannot be converted in place. See [deployment](docs/deployment.md) for the exact reset
+and production commands.
 
 ## Create an editor account
 
@@ -99,7 +126,7 @@ working during the transition.
 
 ```bash
 # Follow application logs
-docker compose logs -f db backend frontend proxy
+docker compose logs -f db backend frontend proxy certbot
 
 # Run database migrations
 docker compose exec backend python manage.py migrate
@@ -112,6 +139,7 @@ docker compose run --rm proxy nginx -t
 docker compose -f docker-compose.yml -f docker-compose.test.yml --profile test run --rm backend python manage.py seed_demo
 docker compose -f docker-compose.yml -f docker-compose.test.yml --profile test run --build --rm functional-tests
 docker compose config --quiet
+LETSENCRYPT_ENABLED=1 docker compose config --quiet
 
 # Stop the stack without deleting content
 docker compose down
@@ -128,8 +156,9 @@ local environment; run the seed command again after the next startup.
 ```text
 .
 ├── backend/                # Wagtail/Django CMS and API
+├── certbot/                # Optional Let's Encrypt renewal loop
 ├── frontend/               # Astro public website
-├── nginx/                  # Reverse-proxy virtual host
+├── nginx/                  # Reverse proxy and dynamic TLS configuration
 ├── tests/functional/       # Playwright browser tests
 ├── docker-compose.test.yml # Functional-test Compose override
 ├── docs/                   # Architecture, operations, security, and ADRs
@@ -173,5 +202,6 @@ cautions. Do not commit database dumps, `.env`, or uploaded media.
 ## Production TODOs
 
 This repository deliberately targets a simple, working local deployment. Before a
-public production launch, add TLS certificates, production-grade static/media
-serving, off-host backups, monitoring, and a deployment-specific secret manager.
+public production launch, configure either the optional direct TLS mode or TLS at the
+load balancer, plus production-grade static/media serving, off-host backups,
+monitoring, and a deployment-specific secret manager.