Kubernetes Deployment

Ephor is distributed as a Helm chart that deploys the API, dashboard, and an optional bundled PostgreSQL instance.

Prerequisites

• Helm 3.10 or later
• Kubernetes 1.25 or later

Installation

The Helm chart is located in charts/ephor/ within the repository:

git clone https://github.com/holbein-io/ephor.git
cd ephor

helm install ephor charts/ephor \
  --namespace ephor \
  --create-namespace

This deploys Ephor with a bundled PostgreSQL instance. The services are available within the cluster but not exposed externally until ingress is configured.

Check the deployment status:

kubectl get pods -n ephor

Ingress

To expose Ephor externally, enable ingress in your values:

# values.yaml
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: ephor.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: ephor-tls
      hosts:
        - ephor.example.com

helm upgrade ephor charts/ephor \
  --namespace ephor \
  --values values.yaml

External Database

For production, use a managed or externally operated PostgreSQL instance instead of the bundled one:

# values.yaml
postgresql:
  enabled: false

externalDatabase:
  host: postgres.example.com
  port: 5432
  name: ephor
  user: ephor
  existingSecret: ephor-db-secret   # Kubernetes Secret with a "password" key

Create the secret:

kubectl create secret generic ephor-db-secret \
  --from-literal=password=<your-password> \
  --namespace ephor

Authentication

In Kubernetes, oauth2-proxy is typically deployed as a separate service or ingress middleware. A common pattern with nginx ingress:

1. Deploy oauth2-proxy:

helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
helm install oauth2-proxy oauth2-proxy/oauth2-proxy \
  --namespace ephor \
  --set config.clientID=<client-id> \
  --set config.clientSecret=<client-secret> \
  --set config.cookieSecret=<random-secret>

2. Configure ingress annotations to use oauth2-proxy for authentication:

ingress:
  annotations:
    nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/auth"
    nginx.ingress.kubernetes.io/auth-signin: "https://$host/oauth2/start?rd=$escaped_request_uri"
    nginx.ingress.kubernetes.io/auth-response-headers: "X-Forwarded-User,X-Forwarded-Email,X-Forwarded-Groups,X-Forwarded-Preferred-Username"

See the Authentication guide for identity provider configuration.

User Directory Provider

Configure user sync in your Helm values:

api:
  env:
    EPHOR_USER_DIRECTORY_PROVIDER: keycloak
    KEYCLOAK_SERVER_URL: https://keycloak.example.com
    KEYCLOAK_REALM: ephor
    KEYCLOAK_CLIENT_ID: ephor-api
    KEYCLOAK_CLIENT_SECRET: <secret>

Resource Configuration

Adjust resource requests and limits based on your environment:

api:
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

dashboard:
  resources:
    requests:
      cpu: 50m
      memory: 64Mi
    limits:
      cpu: 200m
      memory: 128Mi

Upgrading

helm upgrade ephor charts/ephor \
  --namespace ephor \
  --values values.yaml

Review the release notes before upgrading for any breaking changes or required migrations.

Next Steps

• Vulnerability Scanning -- deploy the scanner to discover and scan workloads
• Helm Values Reference -- complete list of configurable values
• Configuration Reference -- all environment variables