Skip to content

Run it on k3s

This installs Workflow on a single-node k3s (or a small k3s cluster) with one CloudNativePG instance and Traefik, using the chart's values-k3s.yaml overlay. For a throwaway local cluster with live reload, see Contributing.

1. Install the CloudNativePG operator

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.1.yaml

cert-manager is optional; add it if Traefik should serve TLS certificates it issues.

2. Write your values

The overlay expects two host names: an internal one for the UI and API, and a public one that serves only Git webhooks and SCIM.

my-values.yaml
config:
  WFM_PUBLIC_URL: "https://workflow.home.example.net"   # UI and API (LAN or VPN)
  WFM_HOOKS_PUBLIC_URL: "https://hooks.example.net"     # Git webhooks and SCIM only
  WFM_ALLOWED_DOMAINS: example.net
  # Sign in with Keycloak (or any OIDC provider); see Integrations → Keycloak.
  WFM_OIDC_PROVIDERS: keycloak
  WFM_OIDC_KEYCLOAK_ISSUER: https://sso.example.net/realms/acme
  WFM_OIDC_KEYCLOAK_CLIENT_ID: workflow

ingress:
  web:
    className: traefik
    hosts: [workflow.home.example.net]
  hooks:
    className: traefik
    hosts: [hooks.example.net]

secrets:
  values:
    WFM_SECRET_KEY: "<32 or more random characters>"
    WFM_OIDC_KEYCLOAK_CLIENT_SECRET: "<client secret>"

Keep secrets out of plain files: the overlay is written for SOPS-encrypted values (helm-secrets or KSOPS), or set secrets.existingSecret to a Secret you create yourself. Every setting is an environment variable; see Configuration.

3. Install

From a checkout of the app repository:

helm upgrade --install wfm deploy/helm/wfm -n wfm --create-namespace \
  -f deploy/helm/wfm/values-k3s.yaml -f my-values.yaml

Tagged releases publish the chart at oci://ghcr.io/workflowproj/charts/wfm. The chart runs the database migrations in a Job: an Argo CD PreSync hook, or with plain Helm a post-install and pre-upgrade hook (on first install the database is created alongside, and the app waits for the migration).

4. Sign in

Open the internal host and sign in through your identity provider with an account from an allowed domain. The first person to sign in becomes the organisation admin; WFM_BOOTSTRAP_ADMINS names others.

Without single sign-on, create the first admin as a local account and sign in with email and password:

kubectl -n wfm exec deploy/wfm-web -- /wfm create-admin --email you@example.net --name "Your Name"

It prints a temporary password, which must be changed at the first sign-in.

Developing Workflow

To work on Workflow itself, with a local k3d cluster and Tilt, see Contributing.