Skip to content

Quick start

First install BenchBar; with Homebrew that is brew install askysh/tap/benchbar askysh/tap/benchbar-app. Then there are two starting points. Pick the one that matches your Mac.

A few words first. A bench is the folder that holds a Frappe installation: the apps in apps/, a Python environment in env/ and the sites in sites/. A site is one Frappe instance in that bench, with its own database and its own address, such as http://macdev:8000. benchbar runs each bench as a launchd agent, the macOS way of keeping a program running in the background.

Without Terminal

Open BenchBar. On a Mac with no bench, its window opens on a short wizard that does the steps below for you:

The first run wizard's Welcome page

  1. Check Your Mac lists what is missing, with a button for the Command Line Tools and the Homebrew command to copy.
  2. New Bench asks for the folder, the profile (v15-lts, v16-lts or a team profile), the app bundle, the site name and the Administrator password, and Review shows the plan before anything changes.
  3. Install shows each step as it runs. macOS asks for your password in its own dialog for the wkhtmltopdf package and the /etc/hosts line; BenchBar never sees it.
  4. Done opens the site and offers a four step walkthrough of the app.

The wizard's Review page, before anything changes

With a bench you already have, choose I Already Have a Bench: Find Benches finds it in a folder and sets up its service after showing the plan, as benchbar adopt does. The rest of this page is the same in Terminal.

You already have a bench

The examples use ~/frappe-bench; put your bench’s folder in its place.

benchbar doctor --bench-dir ~/frappe-bench # read only
benchbar adopt ~/frappe-bench # shows its plan and asks

doctor prints [OK], [WARN] or [FAIL] per check, and a fix: line with the exact command under every WARN and FAIL. It changes nothing.

adopt writes only the service files: Procfile.lean (the list of processes the bench runs), the runner script, the launchd agent, the shell helpers and the /etc/hosts line for the site, then remembers the bench. It shows this plan and waits for your yes. It never runs migrate, build or update, and never touches your apps, sites or databases. The one exception: when the bench uses the same ports as another bench benchbar knows, the plan says so and, after asking, writes the next free port block into sites/common_site_config.json (with a backup first). The /etc/hosts line needs your sudo password once. See install and adopt.

You have no bench yet

benchbar install

install runs three phases with a live step list: system dependencies (Python, Node, MariaDB and Redis from Homebrew), the bench and a site, and the background service. It asks for:

  • the bench folder, ~/frappe-bench unless you change it (or pass --bench-dir);
  • the site name, macdev unless you change it;
  • the site’s Administrator password (or reads ADMIN_PASSWORD). You log in with it later.

A fresh MariaDB gets a generated root password, kept in your Keychain (the macOS password store); set MARIADB_ROOT_PASSWORD to choose your own. When MariaDB already has a root password that the Keychain does not know, install asks for it once and saves it. It asks for sudo once, only when a step ahead needs it: the wkhtmltopdf package and the /etc/hosts line. Started by the BenchBar app (BENCHBAR_SUDO=gui), each of the two shows macOS’s own password dialog instead; cancel one and that step is skipped, with the command to run it by hand, and the install goes on.

The first run downloads a lot and takes a while. Each step ends as done, unchanged or skipped; a failed step stops the run, and the full output is in ~/.local/state/benchbar/logs/ (.benchbar/logs/ in a git checkout of benchbar). Re-running install is safe: it skips what is already done.

To pick the Frappe version or the apps, pass a profile and a bundle, for example benchbar install --profile v16-lts --bundle common. The choices are in Configuration.

Start it

source ~/.zshrc
benchup
open http://macdev:8000

source ~/.zshrc loads the shell helpers such as benchup into this Terminal (a new tab has them already). benchup starts the bench in the background, waits for the site and ends with bench is up: http://macdev:8000.

macdev is the default site name. When you picked another one, or adopted a bench, benchbar status shows the site’s URL; use that.

In the browser, log in as Administrator with the password you gave install (or your existing one), and walk through the setup wizard. You can close Terminal; the bench keeps running until benchdown.

Linux and Windows

On Ubuntu 24.04, clone the repository and run ./benchbar install, then source ~/.bashrc and benchup. See Install: Linux.

On Windows, install BenchBar for Windows (a beta) with the one line in Install: Windows. Its tray opens a first run wizard that sets up WSL, the distro and the bench. See Windows.

What next