azionelab/docs/deployment.md

# Deployment

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;
- `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

Responsibilities:

- listen on public HTTP and HTTPS ports;
- serve built Angular files;
- proxy `/api/` and `/admin/` requests to the backend;
- serve static and media files according to the selected storage layout;
- apply request size and timeout limits appropriate for booking and admin usage.

Public ports:

- `80` for HTTP;
- `443` for HTTPS in production.

### frontend

The frontend is an Angular application using Angular Material.

Deployment options:

- build the Angular app in a Docker build stage and copy static files into the nginx image;
- or run a one-shot build container that writes static files to a shared volume consumed by nginx.

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.

Responsibilities:

- REST API;
- Django admin;
- booking, confirmation, QR generation, and check-in logic;
- transactional capacity validation;
- email sending.

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.

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.

Responsibilities:

- persistent application data;
- reservation and check-in state;
- transactional capacity enforcement.

Use a named Docker volume for database data.

## Networks

Recommended Compose networks:

- `public`: nginx-facing network when needed;
- `internal`: private network for nginx, backend, and db communication.

The database should not be published to the host in production.

## Volumes

Recommended volumes:

- `postgres_data`: PostgreSQL data directory;
- `media`: uploaded media and generated QR assets if stored on disk;
- `static`: collected Django static files if served by nginx from a shared volume.

Generated QR codes may also be generated on demand instead of stored as files. If stored, they must not reveal personal data and access must remain controlled.

## Configuration

Copy `.env.example` to `.env` and replace all placeholder values before running or deploying the stack.

Required backend configuration:

- `DJANGO_SECRET_KEY`;
- `DJANGO_ALLOWED_HOSTS`;
- `DJANGO_CSRF_TRUSTED_ORIGINS`;
- `DATABASE_URL` or equivalent database settings;
- email host, port, username, password, TLS settings, and sender address;
- public site URL used to build confirmation and QR verification links.

Required database configuration:

- database name;
- database user;
- database password;
- data volume path.

Required nginx configuration:

- upstream backend service name and port;
- static frontend root;
- proxy rules for `/api/` and `/admin/`;
- TLS certificate paths for production.

Secrets must be provided through deployment-managed environment variables, Docker secrets, or another secret manager. Do not commit real secret values.

## Example Request Routing

```text
Visitor browser
  -> nginx
    -> Angular static files
    -> /api/ requests proxied to backend:gunicorn
    -> /admin/ requests proxied to backend:gunicorn
Backend
  -> PostgreSQL
  -> SMTP provider
```

## Deployment Commands

The exact commands will be finalized when application code and Compose files are added.

Expected production-style flow:

```bash
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 --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 canonical repository check for the current infrastructure stage is:

```bash
docker compose --env-file .env.example -f infra/docker/compose.yml config
```

## Rollback

Rollback should be designed around immutable images and database backups.

Basic rollback steps:

1. identify the previous known-good image tags or Git commit;
2. stop the current Compose stack;
3. deploy the previous image tags or commit;
4. restore the database from backup only if a migration or data change requires it;
5. run smoke checks for public pages, booking creation, confirmation, and check-in.

Database rollback needs special care once migrations exist. Down migrations or backup restore procedures should be documented before production use.

## Operational Notes

- Configure database backups before accepting real bookings.
- Monitor backend errors, email delivery failures, and check-in failures.
- Keep container images explicitly versioned; do not use `latest` tags.
- Keep the system small until operational needs justify additional services.