Install

From a prepared host to the BenchPress Overview, in six steps.

Who this is for. Whoever owns the host.

Before you start. Every check on
Prerequisites must pass. You need a Frappe v16
bench, a site name, and a shell in the bench directory — the one that holds
apps/, sites/ and env/.

Throughout, replace <site> with your real site name.

Steps

1. Install the app into the bench.

   cd /path/to/your/frappe-bench
   bench get-app https://github.com/Venkateshvenki404224/benchpress --branch version-16
   bench pip install docker
   bench --site <site> install-app benchpress
   bench --site <site> migrate
   

   benchpress declares vpn_management as a required app, so Frappe
   installs that first. It refuses to install without vpn_endpoint_host in
   common_site_config.json and without a reachable wg-agent socket. See
   WireGuard and the VPN plane.

2. Run the setup script.

   bash apps/benchpress/setup.sh <site>
   

   It is idempotent, so a second run reports what is already correct and
   changes nothing. Four steps:

   Step	What it does	Skipped when
   1 of 4	Adds the bench user to the docker group	the user is already a member
   2 of 4	Checks Docker userns-remap or rootless mode	never — it only warns
   3 of 4	Starts benchpress-mariadb and benchpress-redis, and creates the benchpress network and the data volume	the containers are already up
   4 of 4	Writes net.ipv4.ip_forward = 1 under /etc/sysctl.d	forwarding is already on

   Step 2 warns and continues by default. On a host that will carry anything
   you care about, run it as bash apps/benchpress/setup.sh <site> --strict
   instead, which exits non-zero rather than warning. See
   Production safety.

3. Build the frontend. The dashboard is a Vue single-page app and ships as
   source.

   cd apps/benchpress/frontend
   yarn install
   yarn build
   cd -
   bench build --app benchpress
   

4. Open the firewall for WireGuard.

   sudo ufw allow 44556/udp
   

   Open the same port on any cloud firewall or security group in front of the
   host. ufw cannot see that layer.

5. Set the base domain. Open /frontend, then Settings from the
   account menu.

   [Screenshot to be added — docs/images/operator/install/01-settings-domains.png: The BenchPress settings dialog on the Domains panel, with a four-item sidebar reading Domains, Docker, Bench network and Container defaults. The Base domain field holds benchpress.cloud and the Default image field holds frappe/bench latest.]

   base_domain is the only required field on the form, because sites are
   addressed under it as <site>.<base domain>. On this host it is
   benchpress.cloud, and default_image is frappe/bench:latest. Both a
   System Manager and a BenchPress Admin can save this screen. Every other
   field has a working default — see
   Settings reference.

6. Open the dashboard.

   http://<site>:8000/frontend
   

   [Screenshot to be added — docs/images/operator/install/02-overview.png: The BenchPress Overview as an administrator, with four stat tiles reading Running, Stopped, Needs attention and Deploy time, an All instances table, a Recent activity list and a Shared infrastructure panel.]

   The first screen is the Overview: how many environments are running,
   stopped or broken, the average deploy time over the last seven days, and a
   Shared infrastructure panel reporting eleven checks. Seven days is not
   a choice — deploy logs are cleared on that schedule, so no longer window
   has data behind it.

   On this host the four tiles read Running 9 of 15, Stopped 4,
   Needs attention 5, and Deploy time (avg) 51s over 50 runs. A banner
   above them says the VPN is not connected, which is why every Open site
   button reads Open site — VPN off. See
   Register a VPN device.

   The sidebar is five items — Overview, Labs, Templates, Instances and
   Devices — with Settings in the account menu for admins. Build history and
   deploy history are not in the sidebar. They are reached from Labs and
   Instances.

Verify

curl -s -o /dev/null -w '%{http_code}\n' http://<site>:8000/frontend    # 200
bench --site <site> list-apps | grep benchpress                          # present
docker ps --format '{{.Names}}' | grep benchpress-                       # mariadb, redis

Then run the app's own check, which is the honest one — it asks Docker, the
database and the kernel rather than asking the configuration:

bench --site <site> execute benchpress.diagnostics.run_diagnostics

Every row should read pass. A fail row names the fix. See
Diagnostics for what each check means.

Your first bench

The fastest route is Templates: pick a recipe and BenchPress creates the
lab and deploys it in one action. See
Deploy from a template. To describe an
environment yourself, see Create a lab.

The first deploy of a template with no cached image builds one, and that takes
tens of minutes and several gigabytes. Every deploy after it restores from
that image in seconds. See The image cache.

Troubleshooting

Reference

Related

• Prerequisites — everything this page assumes.
• Settings reference — every field and its measured default.
• WireGuard and the VPN plane — the app that owns the tunnel.
• Quick tour — the screens you just installed.