Kubernetes Deployment¶

Kamerplanter is deployed via a single Helm chart that includes all components: backend, frontend, ArangoDB, and Valkey. The container images and the Helm chart are hosted on the GitHub Container Registry (ghcr.io).

Prerequisites¶

Overview: What gets deployed?¶

flowchart TB
    subgraph "Kubernetes Cluster"
        direction TB
        ING["Ingress<br/>(Traefik / nginx)"]

        subgraph "Kamerplanter Namespace"
            FE["Frontend<br/>(Deployment, 2 Replicas)"]
            BE["Backend<br/>(Deployment, 2 Replicas)"]
            DB["ArangoDB<br/>(StatefulSet, 1 Replica)"]
            VK["Valkey<br/>(Deployment, 1 Replica)"]
        end
    end

    ING -->|"/ and /api/*"| FE
    BE --> DB
    BE --> VK
    FE -->|"proxy /api"| BE

    style ING fill:#FF9800,color:#fff
    style FE fill:#66BB6A,color:#fff
    style BE fill:#43A047,color:#fff
    style DB fill:#2E7D32,color:#fff
    style VK fill:#1B5E20,color:#fff

Installation¶

1. Add the Helm repository¶

The Kamerplanter Helm chart is published as an OCI artifact on the GitHub Container Registry:

# OCI registries don't need helm repo add —
# pulling works directly via the OCI URL
helm pull oci://ghcr.io/nolte/charts/kamerplanter --version 0.2.0

echo $GITHUB_TOKEN | helm registry login ghcr.io --username $GITHUB_USER --password-stdin

2. Create the mandatory secrets¶

kubectl create namespace kamerplanter

kubectl create secret generic kamerplanter-secrets \
  --namespace kamerplanter \
  --from-literal=ARANGODB_PASSWORD="your-secure-password" \
  --from-literal=ARANGO_ROOT_PASSWORD="your-secure-password" \
  --from-literal=JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  --from-literal=FERNET_KEY="$(python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')" \
  --from-literal=ERASURE_TOMBSTONE_SALT="$(openssl rand -hex 32)" \
  --from-literal=LOG_PSEUDONYM_SALT="$(openssl rand -hex 32)"

If you switch TimescaleDB on (controllers.timescaledb.enabled: true), the Secret also needs TIMESCALEDB_PASSWORD — see TimescaleDB.

Database credentials¶

The application does not connect to ArangoDB as root but with the account kamerplanter (database.arangodb.appUsername). A helper container app-user in the ArangoDB pod creates or updates it on every start: password from ARANGODB_PASSWORD, read and write access to the application database only, no access to _system. The ArangoDB container itself receives only ARANGO_ROOT_PASSWORD from the Secret.

• ARANGODB_PASSWORD is the application account's password. Choose a value of its own, not the root password.
• ARANGO_ROOT_PASSWORD is needed by the ArangoDB pod only. Put it into a Secret of its own; then the backend no longer sees the root password (it reads all of kamerplanter-secrets via envFrom):

kubectl create secret generic kamerplanter-arangodb-root \
  --namespace kamerplanter \
  --from-literal=ARANGO_ROOT_PASSWORD="$(openssl rand -hex 32)"

database:
  arangodb:
    rootPasswordSecret: kamerplanter-arangodb-root

Full overview of every mandatory secret per enabled feature (e.g. INTERNAL_SERVICE_TOKEN once the AI assistant or image recognition is active): Configuration Matrix — Mandatory secrets.

3. Create a values file¶

Create a values-production.yaml with your customizations:

controllers:
  backend:
    replicas: 2     # (1)!
    containers:
      main:
        envFrom:
          - secret: kamerplanter-secrets    # (2)!
        env:
          ARANGODB_HOST: kamerplanter-arangodb
          ARANGODB_PORT: "8529"
          ARANGODB_DATABASE: kamerplanter
          REDIS_URL: redis://kamerplanter-valkey:6379/0
          CORS_ORIGINS: '["https://plants.example.com"]'
          DEBUG: "false"
          KAMERPLANTER_MODE: full    # (3)!

  frontend:
    replicas: 2

  arangodb:
    statefulset:
      volumeClaimTemplates:
        - name: data
          accessMode: ReadWriteOnce
          size: 10Gi    # (5)!
          advancedMounts:    # (4)!
            main:
              - path: /var/lib/arangodb3

# Attachments in S3 — mandatory with more than one backend replica
storage:
  backend: s3
  s3:
    endpointUrl: https://s3.eu-central-1.amazonaws.com
    region: eu-central-1
    bucket: kamerplanter-prod
    credentialsRef:
      secretName: storage-s3-credentials

ingress:
  main:
    enabled: true
    hosts:
      - host: plants.example.com    # (6)!
        paths:
          - path: /              # /api too: the frontend nginx proxies it to the backend
            pathType: Prefix
            service:
              identifier: frontend

1. Two replicas for rolling updates without downtime. Only with S3 (storage.backend: s3, see below) or a ReadWriteMany volume: on the default ReadWriteOnce volume the chart refuses more than one backend replica, because a second pod on another node never starts (Storage configuration).
2. Pulls ARANGODB_PASSWORD, JWT_SECRET_KEY, FERNET_KEY, ERASURE_TOMBSTONE_SALT and LOG_PSEUDONYM_SALT from the secret created in the previous step — no plain-text passwords in values.yaml.
3. light = without login/tenant system, single user. full (the chart default) = with JWT auth and tenant management. Details: Deployment Profiles.
4. Only the ArangoDB main container mounts the data volume, not the app-user helper container. The chart sets up the root password and the application account itself (see Database credentials); set no envFrom and no ARANGODB_USERNAME here.
5. Adjust the size to your needs. The chart default for the ArangoDB PVC is 5Gi.
6. Your desired hostname. The Ingress controller must be configured for it.

4. Install the Helm chart¶

helm install kamerplanter \
  oci://ghcr.io/nolte/charts/kamerplanter \
  --version 0.2.0 \
  --namespace kamerplanter \
  --create-namespace \
  --values values-production.yaml

5. Verify the deployment¶

# Check pod status
kubectl get pods -n kamerplanter

# Wait for healthy pods
kubectl wait --for=condition=ready pod \
  --all -n kamerplanter --timeout=120s

Expected output:

NAME                                      READY   STATUS    RESTARTS   AGE
kamerplanter-backend-7d8f9b6c4d-abc12     1/1     Running   0          45s
kamerplanter-backend-7d8f9b6c4d-def34     1/1     Running   0          45s
kamerplanter-frontend-5c4d8e7f3b-ghi56    1/1     Running   0          45s
kamerplanter-frontend-5c4d8e7f3b-jkl78    1/1     Running   0          45s
kamerplanter-arangodb-0                   1/1     Running   0          45s
kamerplanter-valkey-0                     1/1     Running   0          45s

Performing updates¶

# Upgrade to a new version
helm upgrade kamerplanter \
  oci://ghcr.io/nolte/charts/kamerplanter \
  --version 0.3.0 \
  --namespace kamerplanter \
  --values values-production.yaml

The backend and frontend deployments perform a rolling update — there is no downtime, as old pods are only terminated once the new ones are ready.

Backend start-up time¶

Before its first request, a new backend pod prepares the database: it creates missing collections and indexes, runs the pending migrations and loads the master-data seeds. Only then does it accept connections. This happens on purpose inside the backend process and not in a separate migration job — an upgrade needs no extra step.

On an empty database that takes about 40 seconds (measured on a workstation; under the chart's 1-CPU limit rather longer). With a long migration, or while another pod is migrating and this one waits, it takes several minutes. So that Kubernetes does not restart the pod during that time, a startupProbe checks the start first; the liveness and readiness probes only begin once it succeeded. Until then the old pod keeps serving.

What that means for you:

• If a pod waits longer than 600 seconds for a migration another pod holds, it stops itself with MigrationBarrierTimeoutError — the backend decides that the start failed, not the kubelet. The maximum start-up time therefore always lies above this wait.
• If a migrating pod is killed, its lock stays for up to 300 seconds; after that another pod takes over. A restart within that window waits instead of migrating right away.
• If a migration needs longer than 15 minutes, raise the startupProbe's failureThreshold before the upgrade (the other probe values are kept). Never lower it below 70: a pod that waited the full 600 seconds for another pod's migration still needs its own start afterward (about 40 seconds, longer under 1 CPU). 10 s × 70 = 700 seconds leave 100 seconds of headroom for that; with less, Kubernetes kills a pod that is legitimately waiting or just finishing its start.
• When scaling up (replicas or the autoscaler), a new pod only helps after its start. Plan scaling in minutes, not seconds.

controllers:
  backend:
    containers:
      main:
        probes:
          startup:
            spec:
              failureThreshold: 180    # 10 s × 180 = 30 minutes

Uninstallation¶

helm uninstall kamerplanter --namespace kamerplanter

kubectl delete pvc --all -n kamerplanter

Monitoring¶

Check logs¶

# Backend logs
kubectl logs -l app.kubernetes.io/component=backend -n kamerplanter --tail=50

# Frontend logs
kubectl logs -l app.kubernetes.io/component=frontend -n kamerplanter --tail=50

# ArangoDB logs
kubectl logs -l app.kubernetes.io/component=arangodb -n kamerplanter --tail=50

Health checks¶

The backend provides two health endpoints:

# Test manually (via port-forward)
kubectl port-forward svc/kamerplanter-backend 8000:8000 -n kamerplanter
curl http://localhost:8000/api/v1/health/ready

Troubleshooting¶

See also¶

• Configuration Matrix — Complete reference of every mandatory secret per feature
• Helm Charts — Detailed description of the chart structure and all configuration options
• ArgoCD — GitOps-based deployment with declarative secret management
• Docker Compose Quick Start — Simpler alternative with Docker Compose
• Docker Compose Permanent Operation — Docker Compose based permanent operation