agentleFS
Smirnov-LabsSmirnov-Labs/claude-skills/skills/operating-frappe-on-kubernetes/SKILL.md

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.

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
  1. Very specific:

    Run Python against the live site by copying a script into a gunicorn pod and exec-ing it in the bench console.

    line 30
  2. Very specific:

    Start the script with import frappe, json and frappe.set_user("Administrator").

    line 43
  3. Very specific:

    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.

    line 63

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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 -g value 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 from frappe.conf.db_name or sites/<site>/site_config.json before any direct dump.
  • sites PVC — sites/<site>/: site_config.json (holds db_name and encryption_key), private/backups/ (where bench backup lands), and common_site_config.json. The encryption_key lives 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 (seed common_site_config.json before set-config -g; encryption_key isn't created by new-site — set it deterministically with the venv python, never an empty one; frappe.utils.health 417s → probe /api/method/ping), and the new-site flags.
  • upgrading-frappe-major-versions.md — the v15→v16 playbook: pre-flight, the Helm 7→8 Redis→Valkey backend flip + the churning migrate Job, bench migrate fix-forward discipline, the frappe.social orphan Module 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.