# Production Deployment Guide

## Overview

AOC runs as a set of Docker containers orchestrated by Docker Compose:

- **nginx** — reverse proxy, TLS termination, static file serving
- **backend** — FastAPI application (Gunicorn + Uvicorn workers)
- **mongo** — MongoDB data store (not exposed externally)

## Prerequisites

- Docker Engine 24+ and Docker Compose plugin
- A server with ports 80/443 reachable from your users
- TLS certificates (place in `nginx/ssl/` or use Let's Encrypt)
- A valid `.env` file at the repo root (see `.env.example`)

## Quick start

1. **Clone / pull the latest release**

   ```bash
   git checkout v1.1.0
   ```

2. **Copy and edit environment variables**

   ```bash
   cp .env.example .env
   # Edit .env and fill in real credentials
   ```

3. **Set the release version**

   ```bash
   export AOC_VERSION=v1.1.0
   ```

4. **Deploy**

   ```bash
   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml up -d
   ```

5. **Verify**

   ```bash
   curl http://localhost/health
   curl http://localhost/api/events
   ```

## Updating to a new release

```bash
export AOC_VERSION=v1.2.0
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```

## Enabling HTTPS

### Option A: Use your own certificates

1. Place `cert.pem` and `key.pem` in `nginx/ssl/`
2. Uncomment the HTTPS server block in `nginx/nginx.conf`
3. Uncomment the HTTP → HTTPS redirect server block
4. Reload nginx:

   ```bash
   docker compose -f docker-compose.prod.yml exec nginx nginx -s reload
   ```

### Option B: Let's Encrypt with Certbot

Replace the `nginx` service in `docker-compose.prod.yml` with a Certbot-friendly setup (e.g., use the `nginx-proxy` + `acme-companion` stack) or mount the Certbot certificates into `nginx/ssl/`.

## Security hardening

- MongoDB is **not exposed** to the host — only the backend container can reach it.
- The backend runs as a non-root (`aoc`) user inside the container.
- nginx adds security headers (`X-Frame-Options`, `X-Content-Type-Options`, etc.).
- Keep `.env` out of version control — it is listed in `.gitignore`.

## Rollback

```bash
export AOC_VERSION=v1.0.3
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```

## Monitoring

- Prometheus metrics: `http://your-host/metrics`
- Health check: `http://your-host/health`
- Container logs:

  ```bash
  docker compose -f docker-compose.prod.yml logs -f backend
  docker compose -f docker-compose.prod.yml logs -f nginx
  docker compose -f docker-compose.prod.yml logs -f mongo
  ```