generated from bisco/codex-bootstrap
168 lines
4.9 KiB
Markdown
168 lines
4.9 KiB
Markdown
# 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;
|
|
- `db`: PostgreSQL database.
|
|
|
|
Only nginx should expose public ports. The backend and database should stay on the internal Compose network.
|
|
|
|
## 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.
|
|
|
|
### 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.
|
|
|
|
### db
|
|
|
|
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
|
|
|
|
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 build
|
|
docker compose run --rm backend python manage.py migrate
|
|
docker compose run --rm backend python manage.py collectstatic --noinput
|
|
docker compose 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
|
|
```
|
|
|
|
The repository does not yet define the canonical Docker-based test command.
|
|
|
|
## 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.
|