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/>(StatefulSet, 1 Replica)"]
        end
    end

    ING -->|"/api/*"| BE
    ING -->|"/"| 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/kamerplanter-helm/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)"

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
          ARANGODB_USERNAME: root
          REDIS_URL: redis://kamerplanter-valkey:6379/0
          CORS_ORIGINS: '["https://plants.example.com"]'
          DEBUG: "false"
          KAMERPLANTER_MODE: full    # (3)!

  frontend:
    replicas: 2

  arangodb:
    containers:
      main:
        envFrom:
          - secret: kamerplanter-secrets    # (4)!
    statefulset:
      volumeClaimTemplates:
        - name: data
          accessMode: ReadWriteOnce
          size: 10Gi    # (5)!
          globalMounts:
            - path: /var/lib/arangodb3

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

1. Two replicas for rolling updates without downtime.
2. Pulls ARANGODB_PASSWORD, JWT_SECRET_KEY, FERNET_KEY and ERASURE_TOMBSTONE_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. ARANGO_ROOT_PASSWORD is also injected from kamerplanter-secrets.
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/kamerplanter-helm/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/kamerplanter-helm/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.

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