operating-frappe-on-kubernetes
Skill6 starsChanged 11 days agoMITView on GitHub
Use when operating, upgrading or debugging Frappe/ERPNext on Kubernetes: bench set-config that won't take, a first site's encryption_key, bench migrate, a major or Helm chart upgrade, Error Log, email or PDF errors.
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adding-an-add-to-claude-buttonSkill
- bd-to-br-migrationSkill
- codex-plan-reviewSkill
- codex-reviewSkill
- debugging-kubernetes-rolloutsSkill
- debugging-nodejs-appsSkill
- de-sloppingSkill
- detect-overengineeringSkill
- evaluating-third-party-toolsSkill
- finding-latest-versionsSkill
- git-reconSkill
- humanizerSkill
- hyprland-luaSkill
- mining-claude-sessionsSkill
- minto-pyramidSkill
- nonstopSkill
- presentation-blueprintSkill
- pr-fixSkill
- pr-landSkill
- prSkill
- watching-pr-bot-reviewsSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Run Python against the live site by copying a script into a gunicorn pod and exec-ing it in the bench console.
- Very specific: line 43
Start the script with import frappe, json and frappe.set_user("Administrator").
- Very specific: line 63
It is NOT in git: If the site or the sites PVC is ever recreated, every set-config -g value is gone and must be re-applied.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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, jsonandfrappe.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 echoesIn [N]:prompts mid-line. - Never pipe multi-block Python in inline. A heredoc's blank lines make the IPython console silently
skip
if/for/defbodies.cpthe file in; inline<<<is only safe for a few flat statements. - Pass an explicit globals dict (
exec(..., {})) so names don't leak between runs.
The config-on-PVC law (read this first)
Frappe's runtime site config lives in sites/common_site_config.json on the sites PVC. Because the
PVC is mounted over the image, any config baked into the image layer or set through Helm values is
masked by the volume and does nothing. The only thing that actually changes runtime config is:
kubectl -n <ns> exec -i <gunicorn-pod> -- bench set-config -g <key> <value>Consequences a future operator must internalize:
- Keys that only work this way:
chromium_path,host_name,server_script_enabled,maintenance_mode, log/mail settings, etc. - It is NOT in git. If the site or the sites PVC is ever recreated, every
set-config -gvalue is gone and must be re-applied. Keep a checklist of the ones your instance needs. - A "config change that had no effect" is almost always something set in the image/Helm instead of via
set-config -g.
The two PVCs (and what only lives there)
- DB PVC — the MariaDB datadir. The database name is a random hash (
_<hex16>), not the site name — read it fromfrappe.conf.db_nameorsites/<site>/site_config.jsonbefore any direct dump. - sites PVC —
sites/<site>/:site_config.json(holdsdb_nameandencryption_key),private/backups/(wherebench backuplands), andcommon_site_config.json. Theencryption_keylives only here — a backup that snapshots the DB PVC but not the sites PVC loses the key and can't decrypt stored passwords. Always back up both.
Reference files
bootstrapping-a-new-site.md— greenfield first-site bootstrap: why the chart setup Jobs churn (use a one-time Job instead), the three traps (seedcommon_site_config.jsonbeforeset-config -g;encryption_keyisn't created bynew-site— set it deterministically with the venv python, never an empty one;frappe.utils.health417s → probe/api/method/ping), and thenew-siteflags.upgrading-frappe-major-versions.md— the v15→v16 playbook: pre-flight, the Helm 7→8 Redis→Valkey backend flip + the churning migrate Job,bench migratefix-forward discipline, thefrappe.socialorphanModule Def, and direct-dump mechanics (the hashed DB name).debugging-error-logs-and-email.md— Error Log triage, Email Account / SMTP + Email Queue proof, headless chromium / PDF, and Script-Reports-need-filters.
Related
- Ledger data and reports (GL/JE writes, dashboards, multi-currency, bank feeds) are a separate concern; use a data-ops skill for those if your setup has one.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

