Tomas Kracmar
0ef50c91f7
Features: - Add /api/ask endpoint for plain-language audit log queries - Regex-based time/entity extraction (no LLM required for parsing) - LLM-powered narrative summarisation with OpenAI-compatible APIs - Graceful fallback to structured bullet lists when LLM is unavailable - Frontend ask panel with markdown rendering and cited events Production: - Harden Dockerfile: non-root user, gunicorn+uvicorn workers - Add docker-compose.prod.yml with internal networks and health checks - Add nginx reverse proxy with security headers - MongoDB no longer exposed externally in production Tests: - 29 new tests for ask parsing, query building, and endpoint behaviour - Fix conftest monkeypatch for routes.ask events collection Bump version to 1.1.0
104 lines
2.6 KiB
Markdown
104 lines
2.6 KiB
Markdown
# 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
|
|
```
|