operating-frappe-on-kubernetes

Operating Frappe / ERPNext on Kubernetes

The manual for keeping a Frappe / ERPNext instance alive on a Kubernetes cluster — platform config, major-version upgrades, and instance debugging. This is the platform & health layer; ledger data and reports (GL/JE writes, dashboards) are out of scope. Keep your instance's own facts (site name, namespace, companies) in a project skill in the repo that deploys it.

When to use

• Standing up the first site on a fresh deploy (greenfield bootstrap — bench new-site).
• A bench migrate / major-version upgrade (v15→v16) or a Helm chart bump.
• Config that "won't take" (chromium_path, host_name, server_script_enabled, maintenance flags).
• Debugging Error Logs, email/SMTP, PDF/chromium, or "permission-locked" financial reports.
• Any direct MariaDB access (dumps, raw SQL) below the bench layer.

The deployment shape

A typical deploy: a Frappe/ERPNext Helm chart under ArgoCD rendering gunicorn (web), nginx, scheduler, and worker pods; external MariaDB and Redis/Valkey (not the chart's bundled ones); and two PVCs — the MariaDB data volume and the Frappe sites volume. You reach the app through the gunicorn pod's bench.

Reaching bench

Run Python against the live site by copying a script into a gunicorn pod and exec-ing it in the bench console. Look the pod up every time; its name changes on every redeploy.

NS=<namespace>; SITE=<site-name>
POD=$(kubectl -n $NS get pods -l 'app.kubernetes.io/component=gunicorn' \
      -o jsonpath='{.items[0].metadata.name}')
kubectl -n $NS cp /tmp/x.py $POD:/tmp/x.py
kubectl -n $NS exec -i $POD -- \
  bench --site $SITE console <<< "exec(open('/tmp/x.py').read(), {})" \
  2>&1 | tr '\n' ' ' | grep -o 'MARK{.*}' | sed 's/^MARK//'

• Start the script with import frappe, json and frappe.set_user("Administrator").
• Print one line of JSON behind a unique marker, print("MARK" + json.dumps(out, default=str)), and grep for it without a ^ anchor: the console echoes In [N]: prompts mid-line.
• Never pipe multi-block Python in inline. A heredoc's blank lines make the IPython console silently skip if / for / def bodies. cp the file in; inline <<< is only safe for a few flat statements.
• Pass an explicit globals dict (exec(..., {})) so names don't leak between runs.