Architecture
The Annolive Helm chart deploys the same on-premise microservices as Docker Compose, orchestrated on Kubernetes. It is designed for single-node clusters (k3s, microk8s) and larger production clusters.
Deployment architecture
Current chart layout: the frontend Service is exposed directly for the UI, and nginx is the API gateway (proxies to backend, serves /static/ and /media/). Backend, worker, model-server, PostgreSQL, and RabbitMQ stay ClusterIP-only inside the cluster.
NodePort and Ingress share the same in-cluster path: UI → frontend Service → frontend Deployment; API → nginx Service → nginx Deployment → backend Service → backend Deployment. The worker has a Deployment only (no Service) — it consumes RabbitMQ. Under Ingress, frontend/nginx Services are usually ClusterIP.
User interaction
Users reach Annolive through one of two access modes:
| Mode | UI | API |
|---|---|---|
| NodePort | http://<node-ip>:30558 | http://<node-ip>:30559 |
| Ingress | http(s)://app.example.com | http(s)://api.example.com |
externalUrls.frontendUrl and externalUrls.backendUrl in Helm values must match exactly what users open in the browser (scheme, host, and port). Mismatches cause CORS, CSRF, or DisallowedHost errors.
Kubernetes resources
| Component | Kind | Role |
|---|---|---|
| backend | Deployment | Django REST API (Gunicorn on port 8000) |
| frontend | Deployment | Next.js UI (port 3000) |
| nginx | Deployment | API gateway; proxies to backend, serves static/media |
| worker | Deployment | Celery worker |
| model-server | Deployment | AI model inference |
| postgres | StatefulSet | PostgreSQL 16 |
| rabbitmq | StatefulSet | Celery message broker |
| setup Job | Job | Fresh install only: runs setup.py (seed domain + admin) |
| init Job | Job | Upgrades: runs init.py (collectstatic + migrate) |
Storage (PVCs)
All persistent data uses PersistentVolumeClaims (no hostPath). Default sizes come from values.yaml in the Helm package:
| PVC | Purpose | Default size |
|---|---|---|
<release>-data | Media, static | 100 Gi |
<release>-postgres-postgres-data-0 | PostgreSQL | 10 Gi |
<release>-rabbitmq-rabbitmq-data-0 | RabbitMQ | 2 Gi |
Set persistence.storageClass if your cluster has no default provisioner (for example k3s local-path). To override sizes at install or grow volumes later, see Installation — Storage.
Bootstrap jobs
- setup Job (
setupJob.enabled: true): runs once on first install. Creates the organisation domain and platform admin. Do not re-run on upgrades. - init Job (
initJob.enabled: true): runs on every Helm upgrade. Applies collectstatic and migrations only.
See Installation for configuration details.