feat: add initial Docker Compose infrastructure

docs/adr/0007-use-docker-compose-for-deployment.md

@@ -0,0 +1,27 @@
+# ADR-0007: Use Docker Compose for Deployment
+
+Date: 2026-04-28
+
+## Status
+
+Accepted
+
+## Context
+
+AzioneLab needs a simple production-oriented deployment for a small theatre company website. The initial runtime services are Django with gunicorn, an Angular frontend served by nginx, PostgreSQL, and an nginx reverse proxy.
+
+The project does not need Celery, Redis, a container orchestrator, or a more complex platform at this stage.
+
+## Decision
+
+Use Docker Compose as the initial deployment mechanism.
+
+The Compose setup will define explicit `backend`, `frontend`, `postgres`, and `nginx` services under `infra/docker/compose.yml`. Configuration is provided through `.env`, PostgreSQL data is stored in a named volume, and only the reverse proxy publishes a host port.
+
+## Consequences
+
+- The deployment remains easy to understand, run, and review.
+- The same topology can support local infrastructure checks and small production deployments.
+- PostgreSQL persistence is explicit through a named volume.
+- The setup can be replaced later if hosting or scaling needs outgrow Docker Compose.
+- Operators must manage `.env`, backups, TLS, and image updates carefully.

docs/architecture.md

@@ -137,10 +137,12 @@ The initial deployment uses Docker Compose with these services:
 - `nginx`: public reverse proxy and static frontend server;
 - `frontend`: Angular build stage or static asset build source;
 - `backend`: Django application served by gunicorn;
-- `db`: PostgreSQL database.
+- `postgres`: PostgreSQL database.
 
 Only nginx should be publicly exposed. The backend and database should be reachable only on the internal Compose network.
 
+The initial Compose files live under `infra/docker/`. The backend and frontend images are placeholders until the Django and Angular applications are implemented.
+
 ## Architectural Constraints
 
 - Keep the booking workflow synchronous and explicit.
@@ -153,4 +155,8 @@ Only nginx should be publicly exposed. The backend and database should be reacha
 
 ## Relevant ADRs
 
-No ADRs are recorded yet. The technology stack and initial constraints are documented here from the project request.
+- [ADR-0001: Use Django Monolith](adr/0001-use-django-monolith.md)
+- [ADR-0002: Do Not Add an Async Task Queue Yet](adr/0002-no-async-task-queue.md)
+- [ADR-0003: Use Opaque Tokens in QR Codes](adr/0003-qr-code-token-strategy.md)
+- [ADR-0004: Use Email Confirmation for Reservations](adr/0004-email-confirmation-flow.md)
+- [ADR-0007: Use Docker Compose for Deployment](adr/0007-use-docker-compose-for-deployment.md)

docs/deployment.md

@@ -5,10 +5,12 @@ AzioneLab should deploy with a simple Docker Compose topology:
 - `nginx`: public reverse proxy and static frontend server;
 - `frontend`: Angular build source or build stage for static assets;
 - `backend`: Django 5.2 LTS application served by gunicorn;
-- `db`: PostgreSQL database.
+- `postgres`: PostgreSQL database.
 
 Only nginx should expose public ports. The backend and database should stay on the internal Compose network.
 
+The initial Compose setup is located at `infra/docker/compose.yml`.
+
 ## Services
 
 ### nginx
@@ -37,6 +39,8 @@ Deployment options:
 
 The first option is preferred for a simple production deployment because nginx can serve immutable built assets without a long-running Node process.
 
+At the infrastructure placeholder stage, the `frontend` service serves a static placeholder page with nginx. The Angular build will replace this placeholder later.
+
 ### backend
 
 The backend is a Django application served by gunicorn.
@@ -51,7 +55,9 @@ Responsibilities:
 
 The backend should run database migrations before or during deployment through an explicit operational command, not as hidden startup magic unless that choice is documented later.
 
-### db
+At the infrastructure placeholder stage, the `backend` service runs gunicorn against a minimal placeholder WSGI application. The real Django application will replace it later.
+
+### postgres
 
 PostgreSQL is the only database service.
 
@@ -84,6 +90,8 @@ Generated QR codes may also be generated on demand instead of stored as files. I
 
 ## Configuration
 
+Copy `.env.example` to `.env` and replace all placeholder values before running or deploying the stack.
+
 Required backend configuration:
 
 - `DJANGO_SECRET_KEY`;
@@ -129,21 +137,25 @@ The exact commands will be finalized when application code and Compose files are
 Expected production-style flow:
 
 ```bash
-docker compose build
-docker compose run --rm backend python manage.py migrate
-docker compose run --rm backend python manage.py collectstatic --noinput
-docker compose up -d
+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 up -d
 ```
 
 Expected validation commands:
 
 ```bash
-docker compose config
-docker compose run --rm backend python manage.py check --deploy
-docker compose run --rm backend python manage.py test
+docker compose --env-file .env.example -f infra/docker/compose.yml config
+docker compose --env-file .env -f infra/docker/compose.yml run --rm backend python manage.py check --deploy
+docker compose --env-file .env -f infra/docker/compose.yml run --rm backend python manage.py test
 ```
 
-The repository does not yet define the canonical Docker-based test command.
+The canonical repository check for the current infrastructure stage is:
+
+```bash
+docker compose --env-file .env.example -f infra/docker/compose.yml config
+```
 
 ## Rollback
 

docs/security-notes.md

@@ -115,12 +115,15 @@ Expected secret configuration:
 
 Use environment variables, Docker secrets, or deployment-managed secret injection. Documentation and example configuration should use placeholders only.
 
+For the Docker Compose setup, copy `.env.example` to `.env` and replace placeholder values outside version control. The repository ignores `.env` and `.env.*` files except `.env.example`.
+
 ## Deployment Security
 
 Deployment should follow least privilege:
 
 - expose only nginx publicly;
 - keep backend and database on an internal Docker network;
+- do not publish backend, frontend, or PostgreSQL ports to the host in production;
 - avoid privileged containers;
 - use explicit image tags rather than `latest`;
 - persist PostgreSQL data in a named volume;

docs/testing.md

@@ -7,7 +7,7 @@ All tests should run inside Docker containers.
 ## Canonical test command
 
 ```bash
-CHANGE_ME
+docker compose --env-file .env.example -f infra/docker/compose.yml config
 ```
 
 ## Test categories