Migrate an existing bench

The same entry point converts a classic bench init bench, or a half-converted one, into a frappe-nix repository. It detects the mode from the directory, so from inside a bench you run the same command as for a new one. Do a dry run first to read the plan.

cd ~/frappe-bench
nix run github:Avunu/frappe-nix -- --dry-run    # inspect the plan first
nix run github:Avunu/frappe-nix                 # then migrate

It is a reconciler, not a converter. It probes what the bench already has, adds only what is missing, repairs drift and never deletes. Running it on an already-migrated bench is a no-op.

Nothing is committed. The result is staged, so git diff --cached is your review. Add --commit to commit it.

What it does

Concretely, it:

• Detects the Frappe version from the branch, then the bench's sites/apps.json, then frappe.__version__, and pins Python and Node from the matching preset.

• Initializes git at the bench root if needed, and registers each app under apps/ as a git submodule pinned at its current commit. Nothing is fast-forwarded. It records the app's actual branch in .gitmodules, without which bench-update --pull silently skips the app, and adds an origin alias when the app only has upstream.

• Vendors apps with no usable remote. The nested .git moves to .frappe-nix-backup/ with a provenance JSON, and the source is committed into the bench. An untracked nested repository is invisible to the flake and would vanish from the build.

• Writes the project files: flake.nix, pyproject.toml, .envrc and uv.lock. It merges into an existing pyproject.toml rather than replacing it, and shims a pyproject.toml for vendored apps that only ship setup.py.

• Regenerates sites/apps.txt and sites/apps.json from the workspace members it just registered. See Apps in a bench. An app that could not become a member is on PYTHONPATH but not registered, and the report says so.

• Reconciles sites/common_site_config.json. It forces the per-bench web and socketio port that the dev shell derives from the bench name and preserves everything else. It drops production-only keys (host_name, http_port, restart_*) and keys the socket setup supersedes (db_host, db_port, the redis_* URLs, file_watcher_port). It blanks mariadb_root_password, since the file is about to be committed.

• Extends .gitignore with a managed block so sites/*/site_config.json, site private/ and public/ data, Procfile, patches.txt, config/*.conf and node_modules stay out of git. It then verifies with git check-ignore that nothing the build needs got excluded.

• Moves a classic env/ virtualenv to .frappe-nix-backup/. A real env/ directory silently defeats the dev shell's ln -sfn and leaves bench on the stale interpreter.

Flags

The complete list is in Scaffolder reference.

After the migration

1. Review what was staged: git diff --cached --stat.

2. If any app ships a package.json without a yarn.lock, run bench-update --node-locks inside the dev shell before the first nix build. The fallback lock is not generated by the migration, because it needs the network and yarn. Evaluation tells you which apps, if any.

3. Enter the shell with direnv allow and start the stack with devenv up. If the bench has no site yet, provision-site creates one. If you declare secrets first, bench restore can clone the site from the latest production backup instead.

What it cannot fix

• An app pinned at a commit that is on no remote branch builds on your machine and nowhere else.

• An app whose remote is unreachable will fail on a fresh clone of the bench.

Both are reported as warnings, and --strict turns the first into an error.

A setup.py-only app that is a submodule cannot be shimmed, because a generated pyproject.toml would sit outside the pinned commit. Vendor it with --vendor <APP>, or fix it upstream.

The bench root must be its own git repository. A bench nested inside another repository is reported, and --force is needed to create a nested repository anyway.