Reference

services.frappe options

Every option of the frappe-nix NixOS module, at the top level and per site, with types and defaults.

Updated2026-10-06

Top-level options

These sit directly under services.frappe.

Option	Type	Default	Notes
`enable`	bool	`false`	Enable the Frappe production deployment (systemd).
`package`	package	required	The default bench package: `builtBench`, or `packages.default` of a bench repository. Sites inherit it unless they set their own.
`user`	str	`"frappe"`	The service user. The module creates it only when the name is `frappe`.
`group`	str	`"frappe"`	The service group. The module creates it only when the name is `frappe`.
`extraEnv`	attrs of str	`{ }`	Extra environment variables for all Frappe services.
`extraPath`	list of package	`[ ]`	Extra packages on the units' `PATH`. systemd's `path` sets `PATH` to exactly the listed packages, so a package that is only in `environment.systemPackages` is invisible to these services. The module already includes `git`, `gzip`, `tar`, `bash` and the MariaDB client tools that Frappe's backup code needs.
`workers`	list of str	`[ "default" "short" "long" ]`	Background worker queues per site. Under the unified runtime they are passed to the runner as `--queue` instead of becoming one unit each.
`web.workers`	int	`4`	Number of gunicorn workers, shared across sites. Ignored when `runtime.enable` is on, with a warning when it is not at its default.
`database.createLocally`	bool	`false`	Enable a local MariaDB. Aggregate: it is on if this or any site requests it.
`database.package`	package	`pkgs.mariadb`	The MariaDB package. Its client library is on `LD_LIBRARY_PATH`.
`redis.createLocally`	bool	`false`	Run a local Redis instance, named `frappe`, unit `redis-frappe`.
`redis.port`	port	`13000`	The port of that Redis. The sites' Redis URLs default to a fixed string and do not follow it.
`runtime.enable`	bool	`true`	One `frappe-runtime` unit per site (web, realtime, jobs and scheduler) instead of separate web, socketio, worker and scheduler units. Needs `frappe-runtime` in the bench's Python environment.
`runtime.jobThreads`	int	`4`	Concurrent background jobs inside the runtime process.
`runtime.webThreads`	int	`0`	Concurrent web requests. `0` keeps `frappe_runtime.asgi`'s own default (`FRAPPE_WEB_THREADS`, itself defaulting to 8). Size the database pool against it.
`runtime.restartAfterRequests`	int	`5000`	Web requests before a graceful restart. `0` means never.
`runtime.restartAfterJobs`	int	`500`	Background jobs before a graceful restart. `0` means never.
`runtime.restartIdleSeconds`	int	`300`	Idle seconds before a graceful restart. `0` means never.
`runtime.requestDrainSeconds`	int	`60`	How long a graceful stop waits for in-flight web requests.
`runtime.jobDrainSeconds`	int	`600`	How long a graceful stop waits for a job in progress. `TimeoutStopSec` is derived from this and `requestDrainSeconds`, so systemd outlasts the drain instead of killing the process partway through.
`runtime.extraArgs`	list of str	`[ ]`	Extra arguments appended to the `frappe-runtime` command line.
`logging.level`	`debug`, `info`, `warning` or `error`	`"warning"`	Threshold for Frappe's application loggers and bench's own log (`FRAPPE_LOG_LEVEL`). See Logging.
`logging.accessLog`	bool	`true`	nginx's access log to the journal as JSON, one object per request. `false` turns access logging off for every virtual host on the machine.
`migrate.enable`	bool	`true`	Run `bench migrate` automatically per site when a new build is deployed.
`migrate.snapshot`	bool	`true`	Take a `mysqldump` snapshot before migrating, as a safety net.
`migrate.rollbackOnFailure`	bool	`true`	Restore the snapshot if the migration fails. No effect when `snapshot` is off.
`migrate.maintenanceMode`	bool	`true`	Toggle maintenance mode around the migration. It is left on if the migration fails.
`migrate.snapshotRetention`	positive int	`3`	Snapshots to keep per site under `<siteDir>/snapshots`.
`migrate.offline.enable`	bool	`false`	Alter large tables online before `bench migrate`, inside the same snapshot and maintenance mode. See Migrate large tables online.
`migrate.offline.rowThreshold`	unsigned int	`100000`	Rows at which a table is altered online rather than by `bench migrate` itself. `0` sends every table with a pending change through it.

Per-site options

These sit under services.frappe.sites.<NAME>, where <NAME> is the site name.

Option	Type	Default	Notes
`enable`	bool	`false`	Enable this site.
`package`	package or null	`null`	Per-site bench package override. Defaults to `services.frappe.package`.
`siteDir`	str	`"/var/lib/frappe/<NAME>"`	The state directory for this site.
`web.port`	port	`8000`	The listen port of the runtime or gunicorn. Ignored when `web.socketPath` is set.
`web.socketPath`	str	`""`	A unix socket instead of a TCP port. nginx reaches it through a generated upstream. The directory must not be `/run` itself: see Run Frappe as a NixOS service.
`socketio.port`	port	`9000`	The Node realtime server port. Only with `runtime.enable = false`, and ignored when `socketio.socketPath` is set.
`socketio.socketPath`	str	`""`	A unix socket for the realtime server (`socketio_uds`). Needs Frappe 15.46 or newer. Only with `runtime.enable = false`; with the runtime it is ignored, with a warning.
`database.createLocally`	bool	`false`	Create a local MariaDB database and user for this site.
`database.host`	str	`"127.0.0.1"`	The database host, used when `socket` is empty.
`database.port`	port	`3306`	The database port, used when `socket` is empty.
`database.socket`	str	`"/run/mysqld/mysqld.sock"`	The database unix socket. Empty disables socket authentication and makes Frappe use `host` and `port`.
`database.name`	str	the site name	The database name, defaulting to the site name with dots and hyphens replaced by underscores.
`database.user`	str	the site name	The database user, defaulting the same way.
`database.passwordFile`	path or null	`null`	A file containing the database password. Merged into `site_config.json` at activation.
`redis.cacheUrl`	str	`"redis://127.0.0.1:13000"`	The Redis cache URL.
`redis.queueUrl`	str	`"redis://127.0.0.1:13000"`	The Redis queue URL.
`redis.socketioUrl`	str	`"redis://127.0.0.1:13000"`	The Redis URL for realtime.
`encryptionKeyFile`	path or null	`null`	A file containing the Frappe encryption key. Merged into `site_config.json` at activation.
`extraConfig`	attrs	`{ }`	Extra keys merged into the base `site_config.json`. Nix values, no secrets.
`extraConfigFiles`	list of path	`[ ]`	JSON files deep-merged into `site_config.json` at activation. This is the place for secrets such as object-storage credentials.
`nginx.enable`	bool	`false`	Create an nginx virtual host for this site.
`nginx.socketPath`	str	`""`	Also serve the virtual host on a unix socket, for a co-located reverse proxy or tunnel connector that terminates TLS elsewhere. The client address then comes from `CF-Connecting-IP`. Requires `nginx.enable`.