CLI and scripts

What you can run from a terminal, and what each one changes.

Who this is for. Somebody working on the host, or on a checkout.

Before you start. BenchPress has no bench subcommands of its own. Nothing
registers a command in hooks.py. Everything below is either the parent
repository's entry.py, a plain Frappe command, or a script in this repository.

entry.py, in the parent repository

entry.py orchestrates the whole control plane stack in Python standard
library only. It has no dependencies to install.

Run it from benchpress_devops, not from this app.

Public deployment is one flag. --domain layers the production overlay,
moves nginx to loopback, puts Traefik on 80 and 443, and issues a wildcard
certificate.

Use --acme-staging while proving out a domain or a new token. Let's Encrypt
allows five certificates for each identifier set every seven days, and a
failed attempt still spends one.

Bench commands

Ordinary Frappe commands, run inside the backend container.

docker compose exec backend bench --site frontend migrate
docker compose exec backend bench --site frontend clear-cache
docker compose exec backend bench --site frontend console
docker compose exec backend bench --site frontend run-tests --app benchpress
docker compose exec backend bench build --app benchpress

After a Python change, restart backend and any worker that imports the
changed module. After a frontend change, run bench build --app benchpress,
then restart backend and frontend.

A multi-line block piped to bench console fails silently. The console is
IPython. A block arriving on a pipe is auto-indented until it no longer parses,
and it produces no output and no error, which reads exactly like a query that
found nothing.

Wrap it in a single exec() call, or use bench execute instead:

bench --site frontend execute frappe.client.get_list \
  --kwargs "{'doctype':'Lab','fields':['name','status'],'limit_page_length':0}"

Use --kwargs, never --args. There is no set-value command. Write a value
with frappe.client.set_value through the same execute call.

Scripts in this repository

Two shell scripts run against an existing bench.

setup.sh --strict exits non-zero when Docker userns-remap is absent or cannot
be verified. Use it on a production host. The default warns and continues, which
suits a development box.

upgrade.sh aborts on any failure and takes a backup first. --dry-run reports
what it would do. It follows Upgrading step for step.

Neither script owns the VPN. Tunnels, peers and address allocation belong to the
vpn_management app.

The four Python scripts

The three drills are measurement harnesses. None of them reimplements the thing
it measures. Every request goes over HTTP to the shipped endpoint, and every
duration is read back out of the run's own Deploy Log.

All three share three safety properties, and they are worth knowing before you
run one on a host serving real users.

density_drill.py fills a network it made, always named bpdrill-<n>, and
asserts the name before the first create. A drill that filled benchpress-0
would take every bench on that bridge offline at the moment it believed it was
measuring capacity.

admission_drill.py stops queue-long for the run unless --allow-deploys.
Every deploy is enqueued after commit, so nothing reaches Redis and the whole
admission decision stays measurable with no worker running.

golden_drill.py --cold is the control arm. It turns restore_from_golden off
for the run and puts it back afterwards, so both arms deploy the same lab.

seed_docs_demo.py --destroy removes only what the script creates and refuses
every other name.

The frontend

cd frontend && yarn dev        # hot reload
cd frontend && yarn test:run   # unit tests
cd e2e && npx playwright test  # end to end

Playwright has its own configuration in e2e/. Running it from the app root
resolves nothing.

Never run yarn lint. That is biome, a different style than this repository
has ever used, and it rewrites every frontend file. Lint with pre-commit:

git add -A && uvx [email protected] run --all-files

git add first. pre-commit skips untracked files, so a new file lints green
while it is invisible and then fails in CI.

The documentation pipeline

Four commands build and gate these pages. Read the exit code, never the last
line of output.

npm run docs:build && npm run docs:lint && npm run docs:score; echo "exit=$?"

Two traps are already handled by the scripts, and both cost a debugging session
to find.

1. Lint the source folder positionally. leadtype lint --src . walks the
   whole project root, finds the generated AGENTS.md, SKILL.md and
   sitemap.md, and reports errors because none of them carries a title.
   Generated files are not pages.
2. The config is docs.config.mjs, not .ts. A TypeScript config needs the
   optional peer dependency jiti. Do not convert it.

Never hand-edit anything under docs-site/ or docs-bundle/. They are
generated, and a gate regenerates and fails on any difference.

Verify

Confirm the whole pipeline is clean:

npm run docs:build && npm run docs:lint && npm run docs:score; echo "exit=$?"

exit=0 is the only passing result.

Troubleshooting

Reference

Related

• Install — the first entry.py run.
• Upgrading — what upgrade.sh automates.
• Configuration — which change needs a rebuild.
• Golden images — what the golden drill measures.