frappe-nix
Jump to
↵select↑↓navigateescclose

Getting started

Scaffold a new Frappe bench with frappe-nix, start the development shell and create your first site.

Updated
Tags
  • quick-start
  • devenv
  • bench
On this page

This page takes you from an empty directory to a running Frappe site. It uses the new-bench path. If you already have a bench or a single app, pick the matching mode in Choose a mode and come back for the shell steps.

Prerequisites

You need:

  • Nix with flakes enabled.

  • direnv, so the shell loads when you enter the directory. Without it, nix develop --no-pure-eval does the same job by hand.

  • git, because apps are tracked as git submodules or as flake inputs.

The generated flake declares the devenv.cachix.org binary cache, so Nix may ask you to trust it the first time you enter the shell.

The --no-pure-eval flag appears in every entry point: the generated .envrc is the single line use flake . --no-pure-eval, and the manual command is nix develop --no-pure-eval. Keep the flag when you load the shell by hand.

1. Scaffold a bench

Run the scaffolder from the directory where the bench should live. With a terminal and no flags it prompts you (using gum) for a Frappe version, a set of apps and a directory name.

nix run github:Avunu/frappe-nix

For a scripted run, pass everything as flags. Without a terminal, --frappe-version is required.

nix run github:Avunu/frappe-nix -- \
  --frappe-version version-15 --apps erpnext,hrms --name mybench mybench

The scaffolder writes the wrapper flake.nix, adds frappe and your apps as git submodules on the branch that matches the version you chose, and runs uv lock. See Create a new bench for the presets, the flags and the files it writes.

2. Enter the shell

cd mybench
direnv allow

Without direnv, run nix develop --no-pure-eval instead. The first entry builds the environment, so it takes a while. When it finishes, a banner prints the bench name, the port, the default site and the most useful commands.

3. Start the services

devenv up

devenv up runs the whole stack through process-compose: MariaDB, Redis, nginx, the Frappe runtime, the asset watcher and Mailpit. Leave it running in this terminal. Everything that can be is on a unix socket, and the ports that remain are derived from the bench name, so you can run several benches at once. The development shell lists every process and port.

4. Create the site

In a second terminal, in the same directory:

provision-site

provision-site creates the site named by FRAPPE_SITE and installs every app listed in sites/apps.txt. It sets the Administrator password to admin unless you pass another one as the first argument:

provision-site '<ADMIN_PASSWORD>'

If the script prompts for a MariaDB root password, leave it blank and press Enter, because the development MariaDB root has none.

provision-site runs bench new-site with --force, which drops an existing database for that site. Do not run it again to pick up an app you added later. When siteName is set, devenv up installs missing apps for you. See Apps in a bench.

5. Open the site

Open http://localhost:<PORT>. The port is 8000 plus an offset hashed from the bench name, and the shell banner prints it. Log in as Administrator with the password you chose.

Anything the site tries to send by email lands in Mailpit instead of leaving your machine. Its web address is in the banner too.

Where next