Kubernetes Installation¶

Deploy Depictio on a Kubernetes cluster using the official Helm chart.

Prerequisites: Kubernetes 1.19+, Helm 3.2.0+, a PV provisioner (if persistence is enabled).

Quick Start¶

Step 1 — Clone and install¶

git clone https://github.com/depictio/depictio.git
cd depictio

helm install depictio helm-charts/depictio \
  -f helm-charts/depictio/values.yaml \
  -n depictio --create-namespace

Step 2 — Wait for pods¶

kubectl get pods -n depictio --watch

All pods should reach Running status: backend, frontend, mongo, minio, redis, celery-worker.

Step 3 — Access Depictio¶

By default services are ClusterIP. Use port-forwarding to access locally:

kubectl port-forward -n depictio service/depictio-frontend 5080:5080

Then open http://localhost:5080.

Service	Port
Frontend (Dash)	5080
Backend API	8058
MinIO Console	9001

Advanced Configuration¶

Custom values file¶

Create a my-values.yaml to override defaults and pass it at install time:

helm install depictio helm-charts/depictio \
  -f helm-charts/depictio/values.yaml \
  -f my-values.yaml \
  -n depictio --create-namespace

To see all configurable parameters:

helm show values helm-charts/depictio

Real-world example (EMBL)¶

The repository includes the EMBL demo deployment values files as a reference. They demonstrate the layered approach: a shared base file overlaid by environment-specific files.

File	Purpose
`values-embl-demo-base.yaml`	Shared settings (storage, resources, auth, MinIO)
`values-embl-demo.yaml`	Demo overlay (ingress, image tags, replicas)
`values-embl-demo-dev.yaml`	Dev overlay (debug flags, reduced resources)
`values-embl-auth.yaml`	Multi-user auth + Google OAuth

Usage pattern:

helm install depictio helm-charts/depictio \
  -f helm-charts/depictio/values.yaml \
  -f helm-charts/depictio/values-embl-demo-base.yaml \
  -f helm-charts/depictio/values-embl-demo.yaml \
  -n depictio --create-namespace

Secrets file

values-embl-secrets.yaml is gitignored — it holds MinIO passwords and OAuth secrets that must be created locally. See values-embl-auth.yaml for the expected key names.

Single-user vs Multi-user mode¶

# my-values.yaml
backend:
  env:
    DEPICTIO_AUTH_SINGLE_USER_MODE: "true"   # default — no login required
    # DEPICTIO_AUTH_PUBLIC_MODE: "true"        # public read-only with sign-in

MinIO credentials¶

# my-values.yaml
secrets:
  minioRootUser: "myadmin"
  minioRootPassword: "mysecurepassword"

External S3 / Bring Your Own MinIO¶

# my-values.yaml
minio:
  enabled: false   # disable bundled MinIO

backend:
  env:
    DEPICTIO_MINIO_PUBLIC_URL: "https://your-minio-host.example.com"
    DEPICTIO_MINIO_EXTERNAL_SERVICE: "true"
    DEPICTIO_MINIO_ROOT_USER: "your-access-key"
    DEPICTIO_MINIO_ROOT_PASSWORD: "your-secret-key"

Ingress¶

Depictio's Helm chart supports three ingress topologies. Pick based on how your cluster's auth and TLS termination work.

Topology	Toggle	When to use
Single ingress (default)	`ingress.enabled: true` only	Frontend, backend API, and MinIO console all share one ingress + annotation set. Right for small/dev clusters or when one OIDC layer covers everything.
Frontend + dedicated backend	`backend.ingress.separateRoute: true`	Apply different auth annotations (or no auth) on the API. Useful when the API needs a different OIDC scope, or when programmatic clients hit `/depictio/api/*` with mTLS or API tokens.
Frontend + dedicated MinIO	`minio.ingress.separateRoute: true`	Same idea for MinIO — typically when MinIO is exposed for direct S3 access from CI runners and shouldn't sit behind the user-facing OIDC.

You can combine the toggles to get all three ingresses separate.

Per-route annotations¶

Each ingress has its own annotations block, applied in isolation:

# my-values.yaml
ingress:
  enabled: true
  host: depictio.yourdomain.com
  tls:
    enabled: true
    secretName: depictio-tls
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    # OIDC annotations applied to the FRONTEND ingress only

backend:
  ingress:
    separateRoute: true
    inheritDefaultAnnotations: false   # don't copy ingress.annotations
    annotations:
      nginx.ingress.kubernetes.io/auth-method: "BASIC"   # different auth
      nginx.ingress.kubernetes.io/proxy-body-size: "200m"

minio:
  ingress:
    separateRoute: true
    inheritDefaultAnnotations: false
    annotations: {}                     # no auth — restrict at network policy

inheritDefaultAnnotations controls whether ingress.annotations are merged into the per-route ingress. Set false when the per-route ingress needs a fundamentally different auth chain.

Network restrictions on dedicated routes

A dedicated MinIO or backend ingress with annotations: {} is unauthenticated at the ingress layer. Restrict access via Kubernetes NetworkPolicies, ingress controller IP whitelisting, or a dedicated private DNS — don't rely on obscurity.

Hosted deployment overlay¶

The values-serve.yaml overlay at helm-charts/depictio/values-serve.yaml is the reference configuration used to deploy depictio on SciLifeLab Serve:

helm upgrade --install depictio ./helm-charts/depictio \
  -f helm-charts/depictio/values.yaml \
  -f helm-charts/depictio/values-serve.yaml

The overlay sets separateRoute: true and inheritDefaultAnnotations: false on both backend and MinIO so the Serve-managed OIDC layer protects only the frontend ingress; backend and MinIO routes are then locked down at the cluster network level.

Celery workers (background callbacks)¶

The Celery worker is included and enabled by default (celery.enabled: true). Design mode always requires Celery. View mode behaviour is controlled separately:

# my-values.yaml
celery:
  replicas: 1
  env:
    DEPICTIO_CELERY_WORKERS: "4"
    DEPICTIO_CELERY_ENABLED: "true"   # async view mode (recommended for production)

Resource limits¶

# my-values.yaml
backend:
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "4Gi"
      cpu: "2"

frontend:
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "2Gi"
      cpu: "1"

Google Analytics¶

# my-values.yaml — or use the bundled example
helm upgrade depictio helm-charts/depictio \
  -f helm-charts/depictio/values.yaml \
  -f helm-charts/depictio/examples/values-google-analytics.yaml

Managing Releases¶

Action	Command
Upgrade	`helm upgrade depictio helm-charts/depictio -f values.yaml -n depictio`
Rollback	`helm rollback depictio -n depictio`
Uninstall	`helm uninstall depictio -n depictio`
Show history	`helm history depictio -n depictio`

Troubleshooting¶

# Check pod status
kubectl get pods -n depictio

# Inspect logs
kubectl logs -n depictio deployment/depictio-backend
kubectl logs -n depictio deployment/depictio-frontend

# Describe a failing pod
kubectl describe pod -n depictio <pod-name>

Common causes: insufficient storage class, PVC pending, image pull errors.