[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[NixOS](/kb/nixos/)Build production images with frappe-nix

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[NixOS](/kb/nixos/)13 articles

- [Overview](/kb/nixos/)
- [A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)
- [Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)
- [Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)
- [Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)
- [Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)
- [Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)
- [Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)
- [Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)
- [Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)
- [Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)
- [Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)
- [Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)
- [WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In NixOS: 13 articles

[Overview](/kb/nixos/)[A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)[Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)[Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)[Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)[Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)[Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)[Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)[Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)[Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)[Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)[Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)[Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)[WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

NixOSBuild production images with frappe-nix

How frappe-nix builds an immutable Frappe bench from each app's yarn.lock, which OCI images it produces, and how to build, load, push and run them.

UpdatedOct 5, 2026

Applies tofrappe-nix main (2026-10)Nix with flakes enabled

Tagsnixosfrappeocicontainers

Reading time8 min

On this page[How the immutable bench is built](#how-the-immutable-bench-is-built)[Python](#python)[node_modules from each yarn.lock](#node_modules-from-each-yarnlock)[Which lockfile wins](#which-lockfile-wins)[Repairing a lock that does not resolve](#repairing-a-lock-that-does-not-resolve)[Compiling assets](#compiling-assets)[The OCI images](#the-oci-images)[The split image set](#the-split-image-set)[Building, loading and pushing](#building-loading-and-pushing)[Running the images](#running-the-images)[Volumes](#volumes)[Environment variables](#environment-variables)[Secrets](#secrets)[A single-host example](#a-single-host-example)[One-off commands](#one-off-commands)[The nginx image](#the-nginx-image)[What the images do not do](#what-the-images-do-not-do)[Related documents](#related-documents)

This document explains how [frappe-nix](https://github.com/Avunu/frappe-nix) turns a Frappe bench into an immutable build, which container images come out of it, and how to build and run them. Use it when you want a Frappe deployment where nothing is installed or compiled at container start.

## How the immutable bench is built

frappe-nix builds one package, `builtBench`, and every image is assembled from it. The package contains the apps, the production Python environment, Node, and the compiled assets. `nix build .#default` builds the same thing.

### Python

The Python environment comes from `uv.lock` through uv2nix. Commit `uv.lock` and the build reads it. Nothing runs `uv sync` at build or start time.

### node_modules from each yarn.lock

Every app with a `package.json` is a node target. So is each immediate subdirectory of an app that has its own `package.json`, such as a nested frontend. Each target gets its own `node_modules`, reproduced from its `yarn.lock`:

frappe-nix reads the lockfile at evaluation time and creates one `fetchurl` per tarball, using the URL and `integrity` the lock already records (or the `#sha1` suffix in older locks). Git dependencies are fetched by commit.

The tarballs are linked into an offline mirror.

nixpkgs' `yarnConfigHook` runs `yarn install --offline --frozen-lockfile --ignore-scripts --ignore-engines --ignore-platform` against that mirror.

You commit no hashes. The derivation sees only `package.json`, `yarn.lock`, `.yarnrc` and `.npmrc`, so editing other files in an app does not rebuild its `node_modules`.

Lifecycle scripts do not run in the sandbox. The frontends frappe-nix was built against need only prebuilt or platform-specific packages, so this works for them. If an app does need extra build steps, `nodeOverrides.<TARGET>` lets you add attributes such as `postPatch` or `nativeBuildInputs` to that target's derivation.

### Which lockfile wins

An app's own `yarn.lock` always wins. If an app ships a `package.json` but no `yarn.lock`, generate a fallback from the bench's dev shell and commit it:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench-update</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--node-locks</span>
```

That writes `node-locks/<APP>/yarn.lock` in a bench (`nix/node-locks/` in app mode, written by `nix run .#relock`). Evaluation warns when a fallback is older than its `package.json`, and when one is unused because the app now ships its own lock.

Evaluation also warns about a target with no lock at all. The package then has no `node_modules` for it, and `builtBench` fails on any such app that has a build script.

### Repairing a lock that does not resolve

Sometimes an upstream `yarn.lock` does not cover its own `package.json`. The offline install then fails with a message like this:

```text
Couldn't find any versions for "<PACKAGE>" that matches "<RANGE>" in our cache
```

You have two options:

Force a repaired fallback over the upstream lock with `bench-update --node-locks <APP>/<SUBDIR>`. The generated lock keeps upstream's pins and fills only the gap.

Leave the frontend out with `nodeNestedFrontendExcludes = [ "<APP>/<SUBDIR>" ];`. frappe-nix then also removes the parent's `build` and `postinstall` scripts that drive that frontend.

### Compiling assets

`builtBench` copies the unbuilt bench tree into the build directory and runs `bench build --production` inside the Nix sandbox. It sets `ESBUILD_TARGET` from the `esbuildTarget` option, which defaults to `es2022`, and `NODE_OPTIONS=--max-old-space-size=4096`. The finished tree, including nested frontend output and rewritten asset links, becomes the package.

Because the environment, `node_modules` and assets are all fixed at build time, a given set of locks and app commits produces the same bench every time.

## The OCI images

Enable the images in your bench flake:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">benchName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<BENCH_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">containers</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">;</span>
```

Each image is built with `dockerTools.buildLayeredImage`, tagged `latest`, and named `<benchName>/<name>`. The unified runtime is on by default, which gives you three images.

| Package     | Image                         | Contents                                                                                     |
| ----------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
| `runtime`   | `<BENCH_NAME>/runtime:latest` | One `frappe-runtime` process: web, realtime, background jobs and scheduler. Listens on 8000. |
| `nginx`     | `<BENCH_NAME>/nginx:latest`   | nginx plus the built bench. Listens on 80.                                                   |
| `bench-cli` | `<BENCH_NAME>/bench:latest`   | The `bench` command for migrations and one-off tasks.                                        |

Note that the package is `bench-cli` but the image is named `bench`.

### The split image set

Set `runtime.enable = false` and frappe-nix builds the classic split instead. You get eight packages instead of three:

| Package          | Image                                | Process                           |
| ---------------- | ------------------------------------ | --------------------------------- |
| `web`            | `<BENCH_NAME>/web:latest`            | gunicorn on port 8000             |
| `scheduler`      | `<BENCH_NAME>/scheduler:latest`      | `bench schedule`                  |
| `worker-default` | `<BENCH_NAME>/worker-default:latest` | `bench worker --queue default`    |
| `worker-short`   | `<BENCH_NAME>/worker-short:latest`   | `bench worker --queue short`      |
| `worker-long`    | `<BENCH_NAME>/worker-long:latest`    | `bench worker --queue long`       |
| `socketio`       | `<BENCH_NAME>/socketio:latest`       | Node realtime server on port 9000 |
| `nginx`          | `<BENCH_NAME>/nginx:latest`          | nginx on port 80                  |
| `bench-cli`      | `<BENCH_NAME>/bench:latest`          | `bench`                           |

Note

The "Production containers" section of the frappe-nix README still describes `web` as the main image. With the default `runtime.enable = true`, `web` does not exist, so build `runtime` instead.

## Building, loading and pushing

Build an image from your bench repository:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">build</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">.#runtime</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">docker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">load</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">result</span>
```

`result` is an image tarball, and `docker load` registers it as `<BENCH_NAME>/runtime:latest`. Repeat with `.#nginx` and `.#bench-cli` for the other two.

frappe-nix declares a `containers.registry` option but does not use it to push anything. Pushing is up to you, using ordinary container tooling:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">docker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">tag</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/runtime:latest</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">registry.example.com/</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/runtime:latest</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">docker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">push</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">registry.example.com/</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/runtime:latest</span>
```

## Running the images

Every image except `nginx` and `socketio` starts through the same entrypoint. It builds the site's configuration from environment variables and mounted secrets, then runs the image's command.

### Volumes

Mount two paths:

`/bench/sites` is a persistent volume for site state.

`/secrets` holds secret files, mounted read-only.

At every start the entrypoint links `apps.txt`, `apps.json` and the compiled `assets` from the image into `/bench/sites`, so a new image always brings its own app registry and assets. `common_site_config.json` is copied in once, and from then on it belongs to you.

### Environment variables

`FRAPPE_SITE` is required. Without it the container exits immediately. The rest have defaults you should usually override:

| Variable                | Default                                 | Becomes                  |
| ----------------------- | --------------------------------------- | ------------------------ |
| `FRAPPE_DB_HOST`        | `127.0.0.1`                             | `db_host`                |
| `FRAPPE_DB_PORT`        | `3306`                                  | `db_port`                |
| `FRAPPE_DB_TYPE`        | `mariadb`                               | `db_type`                |
| `FRAPPE_DB_NAME`        | site name, dots replaced by underscores | `db_name`                |
| `FRAPPE_DB_USER`        | same as `FRAPPE_DB_NAME`'s default      | `db_user`                |
| `FRAPPE_REDIS_CACHE`    | `redis://127.0.0.1:13000`               | `redis_cache`            |
| `FRAPPE_REDIS_QUEUE`    | `redis://127.0.0.1:13000`               | `redis_queue`            |
| `FRAPPE_REDIS_SOCKETIO` | `redis://127.0.0.1:13000`               | `redis_socketio`         |
| `FRAPPE_DB_SOCKET`      | unset                                   | `db_socket`, when set    |
| `FRAPPE_SOCKETIO_UDS`   | unset                                   | `socketio_uds`, when set |

### Secrets

The entrypoint merges these files into `site_config.json`, in this order:

`/secrets/db_password` becomes `db_password`.

`/secrets/encryption_key` becomes `encryption_key`.

Every `/secrets/*.json` is deep-merged over what is already there, which is the place for object-storage credentials and similar settings.

It writes the result with mode `0600`. Secrets never enter the image or the Nix store.

### A single-host example

This starts the runtime image against a MariaDB and Redis you already have:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">docker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-d</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">-runtime</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-p</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">8000:8000</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_SITE=site1.example.com</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_DB_HOST=</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">DB_HOS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">T</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_REDIS_CACHE=redis://</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">REDIS_HOS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">T</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">:6379</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_REDIS_QUEUE=redis://</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">REDIS_HOS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">T</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">:6379</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_REDIS_SOCKETIO=redis://</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">REDIS_HOS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">T</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">:6379</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-v</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">-sites:/bench/sites</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-v</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">SECRETS_DI</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">R</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">:/secrets:ro</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/runtime:latest</span>
```

The default command is `frappe-runtime --host 0.0.0.0 --port 8000 --job-threads 4`, with `/bench` as the working directory. The runtime is not started with `--dev`, the flag that makes it serve assets itself, so put nginx in front of it for `/assets`.

### One-off commands

Run `bench` commands from the `bench-cli` image with the same variables and volumes:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">docker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--rm</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_SITE=site1.example.com</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-e</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">FRAPPE_DB_HOST=</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">DB_HOS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">T</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-v</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">-sites:/bench/sites</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-v</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">SECRETS_DI</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">R</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">:/secrets:ro</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BENCH_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/bench:latest</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--site</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">site1.example.com</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">migrate</span>
```

### The nginx image

The nginx image runs `nginx -c /bench/config/nginx.conf -g "daemon off;"`. frappe-nix does not generate that file. The build copies your bench's `config/` directory into the image, so you supply `config/nginx.conf` yourself.

Warning

The `.gitignore` that frappe-nix scaffolds excludes `config/*.conf`. A flake only sees tracked files, so add your file with `git add -f config/nginx.conf` or it never reaches the image.

## What the images do not do

The entrypoint writes `site_config.json` only. It does not create the site's database, so create or restore the site yourself.

frappe-nix ships no compose file or orchestration for these images.

To run Frappe directly on a NixOS host without containers, see [Running Frappe as a NixOS Service](/kb/nixos/running-frappe-as-a-nixos-service/). It consumes the same `builtBench` package.

Note

This document is derived from the frappe-nix source (`modules/containers.nix`, `lib/bench.nix`, `lib/yarn-lock.nix`) and its README. The run examples have not been executed against a freshly built image, so check them against your own build.

## Related documents

[Frappe Development Environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/), for creating the bench flake these images are built from.

[Running Frappe as a NixOS Service](/kb/nixos/running-frappe-as-a-nixos-service/), for running the same `builtBench` directly on a NixOS host without containers.

[Reference Architecture for Self-Hosting Business Systems](/kb/nixos/reference-architecture-for-self-hosting-business-systems/), for a hosting pattern that runs apps in per-site containers.

Sources

- [github.com/Avunu/frappe-nix](https://github.com/Avunu/frappe-nix)
- [github.com/Avunu/frappe-nix/blob/main/modules/containers.nix](https://github.com/Avunu/frappe-nix/blob/main/modules/containers.nix)
- [github.com/Avunu/frappe-nix/blob/main/lib/bench.nix](https://github.com/Avunu/frappe-nix/blob/main/lib/bench.nix)
- [github.com/Avunu/frappe-nix/blob/main/lib/yarn-lock.nix](https://github.com/Avunu/frappe-nix/blob/main/lib/yarn-lock.nix)

Need help with NixOS?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousBuild a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)[Next →Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [How the immutable bench is built](#how-the-immutable-bench-is-built)
- [Python](#python)
- [node_modules from each yarn.lock](#node_modules-from-each-yarnlock)
- [Which lockfile wins](#which-lockfile-wins)
- [Repairing a lock that does not resolve](#repairing-a-lock-that-does-not-resolve)
- [Compiling assets](#compiling-assets)
- [The OCI images](#the-oci-images)
- [The split image set](#the-split-image-set)
- [Building, loading and pushing](#building-loading-and-pushing)
- [Running the images](#running-the-images)
- [Volumes](#volumes)
- [Environment variables](#environment-variables)
- [Secrets](#secrets)
- [A single-host example](#a-single-host-example)
- [One-off commands](#one-off-commands)
- [The nginx image](#the-nginx-image)
- [What the images do not do](#what-the-images-do-not-do)
- [Related documents](#related-documents)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
