From 7fc0a931ce0a91543cd60be4d995f5b006660a09 Mon Sep 17 00:00:00 2001
From: bisco <bisco@younerd.org>
Date: Wed, 29 Apr 2026 23:00:57 +0200
Subject: [PATCH] docs: add production readiness notes

---
 docs/deployment.md     | 28 ++++++++++++++++++++++++++++
 docs/security-notes.md | 11 +++++++++++
 2 files changed, 39 insertions(+)

diff --git a/docs/deployment.md b/docs/deployment.md
index e85fcdd..4206b81 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,5 +1,28 @@
 # Deployment
 
+## Production Readiness
+
+Before a real deployment, treat `.env.example` as local-development only. Create a separate `.env` for production and replace all placeholder values.
+
+Required production changes:
+
+- set `DJANGO_DEBUG=false`;
+- set a strong random `DJANGO_SECRET_KEY`;
+- set `DJANGO_ALLOWED_HOSTS` to the real public hostnames only;
+- set `DJANGO_CSRF_TRUSTED_ORIGINS` to the real public HTTPS origins;
+- set `SITE_BASE_URL` to the real public HTTPS base URL used for confirmation emails and QR/check-in links;
+- replace the console email backend with real SMTP settings and a valid sender address;
+- publish only nginx and terminate HTTPS at nginx or a trusted upstream reverse proxy;
+- keep `collectstatic --noinput` in the deployment flow before `up -d`;
+- persist the PostgreSQL named volume and configure tested backups before accepting bookings;
+- create the first admin account explicitly with `python manage.py createsuperuser`.
+
+Reverse proxy and HTTPS notes:
+
+- the current nginx template listens on plain HTTP port `80` only and must be adapted for production TLS;
+- if TLS is terminated by another reverse proxy, forward the public host and scheme correctly so generated links remain accurate;
+- keep `SITE_BASE_URL`, `DJANGO_ALLOWED_HOSTS`, and `DJANGO_CSRF_TRUSTED_ORIGINS` aligned with the final public URL.
+
 AzioneLab should deploy with a simple Docker Compose topology:
 
 - `nginx`: public reverse proxy and static frontend server;
@@ -92,12 +115,16 @@ Generated QR codes may also be generated on demand instead of stored as files. I
 
 Copy `.env.example` to `.env` and replace all placeholder values before running or deploying the stack.
 
+`.env.example` is intentionally local-dev oriented. Do not use it unchanged for production.
+
 Required backend configuration:
 
 - `DJANGO_SECRET_KEY`;
 - `DJANGO_ALLOWED_HOSTS`;
 - `DJANGO_CSRF_TRUSTED_ORIGINS`;
+- `DJANGO_DEBUG=false`;
 - `CORS_ALLOWED_ORIGINS`;
+- `SITE_BASE_URL`;
 - `TIME_ZONE`;
 - `DATABASE_URL` or equivalent database settings;
 - email host, port, username, password, TLS settings, and sender address;
@@ -149,6 +176,7 @@ Expected production-style flow:
 docker compose --env-file .env -f infra/docker/compose.yml build
 docker compose --env-file .env -f infra/docker/compose.yml run --rm backend python manage.py migrate
 docker compose --env-file .env -f infra/docker/compose.yml run --rm backend python manage.py collectstatic --noinput
+docker compose --env-file .env -f infra/docker/compose.yml run --rm backend python manage.py createsuperuser
 docker compose --env-file .env -f infra/docker/compose.yml up -d
 ```
 
diff --git a/docs/security-notes.md b/docs/security-notes.md
index 1c10609..8195f60 100644
--- a/docs/security-notes.md
+++ b/docs/security-notes.md
@@ -147,9 +147,20 @@ Deployment should follow least privilege:
 - avoid privileged containers;
 - use explicit image tags rather than `latest`;
 - persist PostgreSQL data in a named volume;
+- run production with `DJANGO_DEBUG=false`;
+- use a strong private `DJANGO_SECRET_KEY`;
+- restrict `DJANGO_ALLOWED_HOSTS` and `DJANGO_CSRF_TRUSTED_ORIGINS` to the real public deployment hosts;
+- keep `SITE_BASE_URL` set to the real public HTTPS URL so email and QR links are correct;
 - configure TLS for production;
 - serve static and media files without exposing private files.
 
+Operational production notes:
+
+- `.env.example` is for local development and examples only, not direct production use;
+- replace the console email backend with real SMTP settings before sending reservation emails;
+- create admin accounts explicitly and protect them with strong passwords and limited access;
+- keep verified database backups for the PostgreSQL volume before accepting live bookings.
+
 ## Logging
 
 Logs should help diagnose operational issues without exposing sensitive data.