feat: natural language query + production hardening
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
This commit is contained in:
103
DEPLOY.md
Normal file
103
DEPLOY.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user