erp-sandbox 0.2.0__tar.gz

erp_sandbox-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datahenge LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erp_sandbox-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: erp-sandbox
+Version: 0.2.0
+Summary: Build a containerized ERPNext development environment from one config.toml
+Author-email: Brian Pond <brian@datahenge.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Datahenge/erp-sandbox
+Project-URL: Issues, https://github.com/Datahenge/erp-sandbox/issues
+Keywords: erpnext,frappe,podman,docker,development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# erp-sandbox
+
+Build a containerized ERPNext development environment from a single
+`config.toml`. Install the tool once, run `erp-sandbox init`, edit one file, run
+one command, and get a working bench with **all source editable from the host**.
+
+Linux only, podman or Docker, no root required. The command is `erp-sandbox`,
+or `sandbox` for short.
+
+---
+
+## Start here
+
+| | |
+|---|---|
+| **Setting one up for the first time** | [docs/setup.md](docs/setup.md) — ~30 min, 11 of it unattended |
+| Working in one day to day | [docs/using.md](docs/using.md) |
+| Something is broken | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Running environments on a shared VPS | [docs/vps.md](docs/vps.md) |
+| Working on `erp-sandbox` itself | [docs/contributing.md](docs/contributing.md) |
+
+The short version, if you have done this before:
+
+```sh
+uv tool install git+https://github.com/Datahenge/erp-sandbox.git
+erp-sandbox init acme-dev && cd ~/erp-sandboxes/acme-dev
+$EDITOR config.toml .erp-sandbox/secrets.env
+erp-sandbox build
+```
+
+Then open `http://localhost:<ports.http>` and log in as `Administrator` with
+the `ADMIN_PASSWORD` you set.
+
+Already installed? `uv tool upgrade erp-sandbox` — one tool serves every
+environment on the machine ([upgrading](docs/using.md#upgrading-erp-sandbox)).
+
+---
+
+## What you get
+
+Four containers, one HTTP port:
+
+| Service | What it does | Reachable from the host |
+|---|---|---|
+| `nginx` | the only entry point — `/` to web, `/socket.io` to realtime | **yes**, `ports.http` |
+| `bench` | honcho running the Procfile: web, socketio, scheduler, workers | no |
+| `mariadb` | the site database | **yes**, `ports.mariadb`, on `127.0.0.1` |
+| `redis` | cache, queue and socketio as logical DBs 0/1/2 | no |
+
+Everything is **bind-mounted from your project directory** — `bench/apps/` the
+cloned source, `bench/env/` the virtualenv, `data/mariadb/` the database. So:
+
+- Edit a `.py` on the host and the reloader picks it up.
+- `git status` works in every app.
+- No `docker cp`, no rebuild to change a line.
+
+You can run several client environments side by side, each with its own ports.
+
+---
+
+## What you need
+
+Linux, Python 3.11+ on the host, podman (rootless) or Docker Engine with its
+compose plugin, `git`, and ~20 GB free. The container images bring their own
+Python, Node and wkhtmltopdf.
+
+The full list, with a command to check each one, is
+[step 1 of setup.md](docs/setup.md#1-check-your-machine--2-min).
+
+---
+
+## Two roots — understand this first
+
+Almost every confusing moment with this tool comes from mixing these up.
+
+| | **The package** | **A project** |
+|---|---|---|
+| What | `erp-sandbox` itself | one client's environment |
+| Holds | templates, compose file, bench `Dockerfile` | `config.toml`, `.erp-sandbox/`, `bench/`, `data/` |
+| Installed | once per machine, shared | created by you, as many as you like |
+| Upgrades | replaced wholesale | never touched |
+
+Every verb except `init` acts on **the environment containing your working
+directory**, found by walking up for `.erp-sandbox/` — the same way `bench` finds
+its bench. So `erp-sandbox bench console` works anywhere inside a project. Use
+`--project DIR` to act on one from outside.
+
+---
+
+## Documentation
+
+**Using the tool**
+
+| | |
+|---|---|
+| First run, end to end | [docs/setup.md](docs/setup.md) |
+| Day-to-day work, editor, debugging, teardown | [docs/using.md](docs/using.md) |
+| Symptom → cause → fix | [docs/troubleshooting.md](docs/troubleshooting.md) |
+
+**Working on the tool**
+
+| | |
+|---|---|
+| Setup, commands, rules | [docs/contributing.md](docs/contributing.md) |
+| What is decided, and why | [docs/decisions.md](docs/decisions.md) |
+| What the tool does, from the developer's side | [docs/functional.md](docs/functional.md) |
+| Architecture, `config.toml` schema, credentials, seeding | [docs/technical.md](docs/technical.md) |
+| Requirements and non-goals | [docs/requirements.md](docs/requirements.md) |
+| Acceptance checklist and the test suite | [docs/testing.md](docs/testing.md) |
+| What changed and when | [CHANGELOG.md](CHANGELOG.md) |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright Datahenge LLC.
+
+erp-sandbox is an independent project, built for ERPNext. It is not affiliated
+with or endorsed by Frappe Technologies. ERPNext and Frappe are trademarks of
+Frappe Technologies Pvt. Ltd.

erp_sandbox-0.2.0/README.md

@@ -0,0 +1,120 @@
+# erp-sandbox
+
+Build a containerized ERPNext development environment from a single
+`config.toml`. Install the tool once, run `erp-sandbox init`, edit one file, run
+one command, and get a working bench with **all source editable from the host**.
+
+Linux only, podman or Docker, no root required. The command is `erp-sandbox`,
+or `sandbox` for short.
+
+---
+
+## Start here
+
+| | |
+|---|---|
+| **Setting one up for the first time** | [docs/setup.md](docs/setup.md) — ~30 min, 11 of it unattended |
+| Working in one day to day | [docs/using.md](docs/using.md) |
+| Something is broken | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Running environments on a shared VPS | [docs/vps.md](docs/vps.md) |
+| Working on `erp-sandbox` itself | [docs/contributing.md](docs/contributing.md) |
+
+The short version, if you have done this before:
+
+```sh
+uv tool install git+https://github.com/Datahenge/erp-sandbox.git
+erp-sandbox init acme-dev && cd ~/erp-sandboxes/acme-dev
+$EDITOR config.toml .erp-sandbox/secrets.env
+erp-sandbox build
+```
+
+Then open `http://localhost:<ports.http>` and log in as `Administrator` with
+the `ADMIN_PASSWORD` you set.
+
+Already installed? `uv tool upgrade erp-sandbox` — one tool serves every
+environment on the machine ([upgrading](docs/using.md#upgrading-erp-sandbox)).
+
+---
+
+## What you get
+
+Four containers, one HTTP port:
+
+| Service | What it does | Reachable from the host |
+|---|---|---|
+| `nginx` | the only entry point — `/` to web, `/socket.io` to realtime | **yes**, `ports.http` |
+| `bench` | honcho running the Procfile: web, socketio, scheduler, workers | no |
+| `mariadb` | the site database | **yes**, `ports.mariadb`, on `127.0.0.1` |
+| `redis` | cache, queue and socketio as logical DBs 0/1/2 | no |
+
+Everything is **bind-mounted from your project directory** — `bench/apps/` the
+cloned source, `bench/env/` the virtualenv, `data/mariadb/` the database. So:
+
+- Edit a `.py` on the host and the reloader picks it up.
+- `git status` works in every app.
+- No `docker cp`, no rebuild to change a line.
+
+You can run several client environments side by side, each with its own ports.
+
+---
+
+## What you need
+
+Linux, Python 3.11+ on the host, podman (rootless) or Docker Engine with its
+compose plugin, `git`, and ~20 GB free. The container images bring their own
+Python, Node and wkhtmltopdf.
+
+The full list, with a command to check each one, is
+[step 1 of setup.md](docs/setup.md#1-check-your-machine--2-min).
+
+---
+
+## Two roots — understand this first
+
+Almost every confusing moment with this tool comes from mixing these up.
+
+| | **The package** | **A project** |
+|---|---|---|
+| What | `erp-sandbox` itself | one client's environment |
+| Holds | templates, compose file, bench `Dockerfile` | `config.toml`, `.erp-sandbox/`, `bench/`, `data/` |
+| Installed | once per machine, shared | created by you, as many as you like |
+| Upgrades | replaced wholesale | never touched |
+
+Every verb except `init` acts on **the environment containing your working
+directory**, found by walking up for `.erp-sandbox/` — the same way `bench` finds
+its bench. So `erp-sandbox bench console` works anywhere inside a project. Use
+`--project DIR` to act on one from outside.
+
+---
+
+## Documentation
+
+**Using the tool**
+
+| | |
+|---|---|
+| First run, end to end | [docs/setup.md](docs/setup.md) |
+| Day-to-day work, editor, debugging, teardown | [docs/using.md](docs/using.md) |
+| Symptom → cause → fix | [docs/troubleshooting.md](docs/troubleshooting.md) |
+
+**Working on the tool**
+
+| | |
+|---|---|
+| Setup, commands, rules | [docs/contributing.md](docs/contributing.md) |
+| What is decided, and why | [docs/decisions.md](docs/decisions.md) |
+| What the tool does, from the developer's side | [docs/functional.md](docs/functional.md) |
+| Architecture, `config.toml` schema, credentials, seeding | [docs/technical.md](docs/technical.md) |
+| Requirements and non-goals | [docs/requirements.md](docs/requirements.md) |
+| Acceptance checklist and the test suite | [docs/testing.md](docs/testing.md) |
+| What changed and when | [CHANGELOG.md](CHANGELOG.md) |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright Datahenge LLC.
+
+erp-sandbox is an independent project, built for ERPNext. It is not affiliated
+with or endorsed by Frappe Technologies. ERPNext and Frappe are trademarks of
+Frappe Technologies Pvt. Ltd.

erp_sandbox-0.2.0/erp_sandbox/__init__.py

@@ -0,0 +1,10 @@
+"""
+erp-sandbox — build a containerized ERPNext development environment from one
+config.toml.
+
+Installed with `pipx install` or `uv tool install`, never `pip install`:
+modern Debian marks the system interpreter externally managed (PEP 668).
+See decision #27.
+"""
+
+__version__ = "0.2.0"

erp_sandbox-0.2.0/erp_sandbox/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m erp_sandbox`, equivalent to the `erp-sandbox` console script."""
+
+from erp_sandbox.cli import main
+
+raise SystemExit(main())

erp_sandbox-0.2.0/erp_sandbox/assets/conf/mariadb/erpnext.cnf

@@ -0,0 +1,30 @@
+# MariaDB settings Frappe requires, plus a few that make a dev database
+# pleasant. Committed and generic: nothing here is client-specific, and the
+# port is passed on the command line from config.toml rather than set here.
+
+[mysqld]
+# Frappe will not install on a database that is not utf8mb4. The handshake
+# line is the one people miss: without it the client negotiates latin1 and
+# emoji or accented characters arrive mangled rather than rejected.
+character-set-client-handshake = FALSE
+character-set-server           = utf8mb4
+collation-server               = utf8mb4_unicode_ci
+
+# v12-era Frappe assumes this. Leaving the 10.4 default of
+# STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,... breaks patches that insert
+# zero dates.
+sql_mode = ""
+
+# A development box is not a production server: prefer fast restarts and low
+# memory over durability. A dev database that loses the last second of writes
+# on a hard kill is not a problem; one that takes two minutes to start is.
+innodb_flush_log_at_trx_commit = 2
+innodb_file_per_table          = 1
+
+max_allowed_packet = 256M
+
+[mysql]
+default-character-set = utf8mb4
+
+[client]
+default-character-set = utf8mb4

erp_sandbox-0.2.0/erp_sandbox/assets/conf/nginx-00-resolver.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Teach nginx to resolve upstream names at request time instead of at startup.
+#
+# Without this, nginx refuses to start when the bench container is not running:
+# a name in an `upstream` block is resolved once, at config load, and a failure
+# there is fatal. That is the wrong behaviour for a development environment,
+# where the bench is stopped and restarted constantly and the developer needs
+# the proxy to stay up and say 502 rather than vanish with it.
+#
+# The nameserver address cannot be hardcoded: Docker publishes an embedded DNS
+# server at 127.0.0.11, podman runs aardvark-dns on the network's gateway. Both
+# write it into the container's own /etc/resolv.conf, so read it from there.
+#
+# The official nginx image runs every executable in /docker-entrypoint.d before
+# starting nginx; this is mounted in as one of them.
+
+set -eu
+
+target=/etc/nginx/conf.d/resolver.conf
+
+servers="$(awk '/^nameserver/ { printf "%s ", $2 }' /etc/resolv.conf)"
+
+if [ -z "$servers" ]; then
+    echo "00-resolver.sh: no nameserver in /etc/resolv.conf; leaving nginx to resolve at startup" >&2
+    exit 0
+fi
+
+# ipv6=off because an AAAA lookup for a container name that only has an A
+# record produces a slow, confusing failure on some engines.
+printf 'resolver %s valid=10s ipv6=off;\nresolver_timeout 5s;\n' "$servers" > "$target"
+
+echo "00-resolver.sh: nginx will resolve upstreams via: $servers"

erp_sandbox-0.2.0/erp_sandbox/assets/conf/redis/redis.conf

@@ -0,0 +1,22 @@
+# One Redis container, three logical databases (decision #6): 0 cache,
+# 1 queue, 2 socketio. Production uses three separate containers; this
+# deliberately does not.
+#
+# The port is supplied on the command line from config.toml, so it is not set
+# here -- there is no second place for it to disagree.
+
+# Nothing in here is worth keeping across a restart. The cache rebuilds, the
+# queues refill, and socketio state is per-connection. Persistence would buy
+# nothing and cost fork pauses.
+save ""
+appendonly no
+
+# Bound to every interface *inside the container*. The container network is the
+# boundary, and the port is never published to the host (decision #16).
+bind 0.0.0.0
+protected-mode no
+
+# Evict cache entries rather than returning errors when memory runs short.
+maxmemory-policy allkeys-lru
+
+loglevel notice

erp_sandbox-0.2.0/erp_sandbox/assets/config.sample.toml

@@ -0,0 +1,273 @@
+# ═══ config.toml ══════════════════════════════════════════════════════════
+#
+# The only file you edit. Everything else is generated from it by
+# `erp-sandbox render`, and generated files are overwritten on every render.
+#
+#   erp-sandbox init acme-dev && cd acme-dev
+#   $EDITOR config.toml
+#   erp-sandbox build
+#
+# config.toml is gitignored. This sample is committed, so every value in it is
+# a placeholder -- acme, example.com. Nothing real belongs here.
+
+[project]
+name     = "acme"                # compose project + container name prefix
+                                 #   lowercase, [a-z0-9_-]
+site     = "site_acme1"          # Frappe site name; becomes bench/sites/<name>
+timezone = "America/Los_Angeles"
+
+# ─── Host-published ports ────────────────────────────────────────────────
+# Only these two reach the host. Change them if something already listens;
+# preflight checks both before the build does any work.
+[ports]
+http    = 8101                   # nginx: the URL you open in a browser
+mariadb = 3316                   # for DBeaver / DataGrip / the mysql client
+# bind  = "127.0.0.1"            # where http is published; this is the default.
+                                 #   "0.0.0.0" reaches every interface -- under
+                                 #   Docker that bypasses ufw. mariadb is always
+                                 #   loopback.
+
+# ─── Internal ports ──────────────────────────────────────────────────────
+# Container network only -- nothing here is published. You would change these
+# only to avoid a collision inside the bench container. socketio and the file
+# watcher stay internal deliberately: nginx multiplexes /socket.io onto
+# ports.http, which is what keeps realtime working through one port.
+[internal_ports]
+web          = 8000
+socketio     = 9000
+file_watcher = 6787
+mariadb      = 3306
+redis        = 6379
+
+# ─── The stack ───────────────────────────────────────────────────────────
+# These pin the toolchain. The defaults below are correct for ERPNext v12.
+# A v13/v14 environment changes them.
+[stack]
+frappe_version = 12               # which Frappe series; must be one this
+                                  # tool knows how to build (decision #28)
+base_image    = "docker.io/library/debian:bullseye-slim"  # bullseye = python 3.9
+python        = "3.9"
+node          = "12.22.12"
+yarn          = "1.22.22"           # yarn 1.x; v12 asset builds predate berry
+wkhtmltopdf   = "0.12.6.1-2"     # packaging release, NOT the wkhtmltopdf version;
+                                 #   must be a patched-qt build, and the release
+                                 #   that ships a bullseye .deb is 0.12.6.1-2
+bench         = "5.24.1"
+mariadb_image = "docker.io/library/mariadb:10.4.6"
+redis_image   = "docker.io/library/redis:6.2-bullseye"
+nginx_image   = "docker.io/library/nginx:1.24-bullseye"
+
+# System packages an app needs in order to *build*. Empty for a stock
+# Frappe/ERPNext bench. An app with a compiled dependency will say so in its own
+# README -- e.g. one wrapping a system service may need that service's -dev
+# package. Debian package names, installed into the bench image.
+extra_packages = []
+
+# Ceilings pip may not resolve past while installing the apps, as a pip
+# constraints file (`-c`). NOT a requirements file: nothing here is installed,
+# and a package is only capped if some app already asks for it. It applies to
+# every app's install, not one of them.
+#
+# `erp-sandbox init` seeds this from the Frappe series template. It is yours to
+# edit, and whatever it says is what the build uses -- an empty list means no
+# constraints at all. erp-sandbox never adds one back.
+#
+# Why the v12 seed exists: vanilla v12 pins openpyxl==2.6.4, whose compat layer
+# reads numpy.float, removed in numpy 1.24. Nothing in a 2019 requirements.txt
+# caps numpy, so pip is free to install 2.x and the site build dies importing
+# openpyxl.
+#
+# Empty it if your fork has modernised pins. A fork pinning numpy==1.26.4 has
+# no candidate left under this cap, and pip says only "No matching distribution
+# found for numpy==1.26.4" -- see docs/troubleshooting.md.
+#
+# One entry per package, no spaces inside an entry: "numpy<1.24", not
+# "numpy < 1.24".
+pip_constraints = ["numpy<1.24"]
+
+# ─── The tool itself ─────────────────────────────────────────────────────
+# The oldest erp-sandbox that can build this environment.
+#
+# One installed erp-sandbox now serves every environment on the machine, so
+# upgrading it changes all of them at once. This is how an environment says
+# what it needs: preflight refuses to build with an older tool rather than
+# failing somewhere in the middle on a feature that did not exist yet.
+#
+# `erp-sandbox init` writes the version that created the environment. Raise it by
+# hand if you come to depend on something newer.
+
+[erp-sandbox]
+min_version = "0.1.0"
+
+# ─── Applications ────────────────────────────────────────────────────────
+# Order matters: it is the clone order and the install order. frappe must be
+# first. Frappe and ERPNext are not special-cased -- they are entries like any
+# other, which is what makes this tool generic.
+#
+#   name  — the Frappe app name; must match the app's own module name
+#   repo  — a clone URL: https://host/path, ssh://user@host/path, or the
+#           scp-style user@host:path. Both schemes are supported.
+#   ref   — branch or tag; whatever `git checkout` accepts
+#   install — false clones the app and leaves it off the site
+#
+#   requires_credentials — true means this clone needs the [credentials.<host>]
+#           entry for its host. It is not the same question as "is the
+#           repository private": an ssh remote to a private repository
+#           authenticates with your own key, which this tool does not manage,
+#           so it takes false. Set true only for an https clone that needs a
+#           token, and preflight will refuse the combination of true and ssh.
+#
+#   blobless — optional, false when absent; set true below for frappe and
+#           erpnext, the two clones that cost the disk. true clones with
+#           --filter=blob:none: every commit and branch arrives, but the
+#           contents of files at old commits are fetched only when a command
+#           asks for one. Measured on 2026-08-23, frappe and erpnext at
+#           version-12 carry 1.4 GiB of objects between them and about 70 MiB
+#           of that is commits, trees and the current files.
+#           The price is that `git log -p`, `git blame` on an old file, and
+#           `git bisect` need the network, and are slower the first time. Leave
+#           it false for an app you dig through history in; it is refused
+#           outright for an app with requires_credentials = true, because those
+#           later fetches happen long after the token is gone. Applies when the
+#           app is cloned -- setting it later does not shrink a clone you
+#           already have, and clearing it does not fetch the history back.
+
+[[apps]]
+name                 = "frappe"
+repo                 = "https://github.com/frappe/frappe.git"
+ref                  = "version-12"
+requires_credentials = false
+install              = true
+blobless             = true       # history arrives; old file contents on demand
+
+[[apps]]
+name                 = "erpnext"
+repo                 = "https://github.com/frappe/erpnext.git"
+ref                  = "version-12"
+requires_credentials = false
+install              = true
+blobless             = true       # most of this clone is history you may never read
+
+# Your own apps go here. They are commented out so that `erp-sandbox build` works
+# immediately after `erp-sandbox init` -- frappe and erpnext above are public, so
+# an unedited config produces a stock ERPNext and proves the machine works.
+# Uncomment and edit when you have real repositories to add.
+#
+# [[apps]]
+# name                 = "acme_app"
+# repo                 = "https://git.example.com/acme/acme_app.git"
+# ref                  = "master"
+# requires_credentials = true     # needs the [credentials."git.example.com"] entry below
+# install              = true
+#
+# [[apps]]
+# name                 = "acme_tools"
+# repo                 = "git@git.example.com:acme/acme_tools.git"
+# ref                  = "version-12"
+# requires_credentials = false    # ssh: your own key authenticates, no token needed
+# install              = false    # cloned and importable, but not installed on the site
+
+# ─── Credentials ─────────────────────────────────────────────────────────
+# Keyed by git host, so GitHub and GitLab repos can coexist in one config.
+# A host needs an entry here only if some app on it has
+# requires_credentials = true.
+#
+# Prefer "env:NAME". The token then lives in your shell and never touches a
+# file. A literal is accepted -- config.toml is gitignored -- but the renderer
+# warns, because the value is now on disk.
+#
+# The token is used host-side only, by erp-sandbox fetch, for the
+# duration of one clone. It never enters a container, an image layer, or a
+# build argument.
+# Commented out along with the apps that needed them. A [credentials] entry is
+# required only for an app with requires_credentials = true.
+#
+# [credentials."git.example.com"]
+# username = "your-username"
+# token    = "env:GIT_PAT"
+#
+# [credentials."gitlab.com"]
+# username = "your-username"
+# token    = "env:GITLAB_PAT"
+
+# ─── Where secrets come from ─────────────────────────────────────────────
+# Every "env:NAME" above is looked up in your shell first, then in this file.
+# The shell wins, so `export NAME=...` overrides the file for one run.
+# preflight prints which source answered for each secret.
+#
+# Omit this section to use the default, secrets.env, next to config.toml.
+# Set file = "" to use the shell only. The path may be absolute or start with
+# ~, which is how you keep secrets outside the repository entirely.
+#
+# It cannot be ".env" -- render.py generates that file for compose and
+# overwrites it on every render.
+# [secrets]
+# file = "secrets.env"
+
+# ─── Database ────────────────────────────────────────────────────────────
+[database]
+root_password  = "env:DB_ROOT_PASSWORD"
+
+# seed = how the site's database gets its contents.
+#   "new_site"       — bench new-site, then install each install = true app.
+#                      Empty but working. The only mode that needs no client
+#                      data, and therefore the default.
+#   "sql_dump"       — restore a raw SQL dump you supply.
+#   "frappe_backup"  — bench restore a frappe-native backup tarball.
+#
+# The tool never distributes client data. Dump files are yours, at a path on
+# your own disk.
+seed           = "new_site"
+dump_path      = ""              # required unless seed = "new_site"
+
+# REQUIRED with a restored dump, and there is no way to recover from getting
+# it wrong quietly: without the encryption_key that matches the dump, every
+# stored password in the restored site is unreadable, and you find out weeks
+# later when an integration cannot authenticate. Prefer "env:NAME".
+encryption_key = ""
+
+[site]
+admin_password = "env:ADMIN_PASSWORD"
+
+# Shared VPS only: the https address Caddy serves this site on, one subdomain
+# per environment. It becomes Frappe's host_name, so emails, webhook payloads
+# and OAuth callbacks carry it, and `erp-sandbox proxy-snippet` prints the Caddy
+# block for it. Leave it unset on a laptop. See docs/vps.md.
+# public_url = "https://acme.dev.example.com"
+
+# ─── Debugging ───────────────────────────────────────────────────────────
+# Opt-in remote debugging with debugpy: set a breakpoint in VSCode (or any
+# DAP-speaking editor) and step through the framework and your own apps.
+#
+# Off by default, because turning it on publishes a THIRD host port -- and a
+# debug port runs arbitrary code by design, so it is bound to 127.0.0.1 only.
+#
+# Turning this on and re-rendering writes the attach configuration into
+# <name>.code-workspace. Open that workspace -- File > Open Workspace from
+# File, not the folder -- and pick it from the debug dropdown. Opening the
+# folder instead leaves the path mapping unresolved, and the editor sees host
+# paths while the interpreter reports container ones, so breakpoints bind to
+# nothing and never fire without reporting anything.
+#
+# target = "web" is the only value. The other long-running frappe processes
+# reach your code through a fork that debugpy does not follow, so a breakpoint
+# in them never fires -- see docs/technical.md section 10 before assuming a
+# worker can be debugged this way.
+#
+# Enabling this turns OFF the web server's auto-reload. That is deliberate and
+# unavoidable: the reloader re-executes the server, which drops the debugger.
+# While debugging, restart the web process to pick up code changes:
+#
+#   erp-sandbox restart bench
+#
+# Omit this section entirely to leave debugging off.
+[debug]
+enabled = false
+target  = "web"
+port    = 5678
+
+# ─── Frappe runtime settings → common_site_config.json ───────────────────
+[frappe]
+developer_mode     = 1
+background_workers = 1           # worker processes per queue (short/long/default)
+gunicorn_workers   = 2