[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/)Run WordPress on FrankenPHP with wordpress-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/)

NixOSRun WordPress on FrankenPHP with wordpress-nix

Build WordPress on FrankenPHP as an OCI image or a NixOS service, choose state or git mode, and develop locally with devenv using the wordpress-nix flake.

UpdatedOct 5, 2026

Applies towordpress-nix (nixos-unstable)FrankenPHPPHP 8.2 to 8.5 (ZTS)NixOS

Tagsnixoswordpressfrankenphpoci

Reading time13 min

On this page[How the pieces fit](#how-the-pieces-fit)[The PHP build](#the-php-build)[Deploy on NixOS](#deploy-on-nixos)[State mode: a mutable site](#state-mode-a-mutable-site)[Git mode: a source-managed site](#git-mode-a-source-managed-site)[What the module sets up](#what-the-module-sets-up)[Operating the site](#operating-the-site)[Common options](#common-options)[Build the OCI image](#build-the-oci-image)[Configure the container](#configure-the-container)[Develop locally with devenv](#develop-locally-with-devenv)[Start the site](#start-the-site)[How the dev shell is laid out](#how-the-dev-shell-is-laid-out)[Choose the dev database](#choose-the-dev-database)[Bootstrap a site repository](#bootstrap-a-site-repository)[Related documents](#related-documents)

[wordpress-nix](https://github.com/Avunu/wordpress-nix) is a Nix flake that runs WordPress on [FrankenPHP](https://frankenphp.dev/) two ways: as an OCI container image, or as a NixOS service (`services.wordpress-nix`). Use this document when you want to deploy a WordPress site on a NixOS host, build an image for a container platform, or run the same stack on a laptop with devenv.

## How the pieces fit

Both deployment paths share one PHP build and one FrankenPHP build, so a site behaves the same in a container, on NixOS and in the dev shell.

| Path         | Entry point                                                           | Use it when                                |
| ------------ | --------------------------------------------------------------------- | ------------------------------------------ |
| NixOS module | `nixosModules.default`, option set `services.wordpress-nix`           | You run WordPress directly on a NixOS host |
| OCI image    | `packages.<system>.wordpress-php83` and friends, or `lib.mkSiteImage` | You deploy to a container platform         |
| Dev shell    | `flakeModules.default`, option set `perSystem.wordpress-nix`          | You develop a site repo locally            |

### The PHP build

FrankenPHP embeds PHP, and the embed requires a thread-safe (ZTS) build. `lib/php.nix` wraps the nixpkgs PHP you choose with ZTS enabled and a WordPress-ready extension set: `mysqli`, `curl`, `dom`, `exif`, `gd`, `intl`, `mbstring`, `openssl`, `sodium`, `zip`, `apcu` and the other extensions WordPress recommends.

**Versions.** The flake builds images for PHP 8.2, 8.3, 8.4 and 8.5. The NixOS module defaults to `pkgs.php83`.

**Optimization.** The build uses clang with `-O3` and LTO, plus a CPU baseline flag (`-march=x86-64-v3` on x86_64, `-mcpu=neoverse-n1` on aarch64). Set `phpOptimize = false` to skip that pass for a faster build.

**JIT.** nixpkgs disables opcache JIT in ZTS builds before PHP 8.5, which would make `opcache.jit` inert. The flake turns it back on for 8.2 to 8.4. From 8.5, opcache is part of the interpreter and no override is needed.

**Defaults.**`conf/php.ini` sets `memory_limit = 1G`, `max_execution_time = 300`, 100 MB upload and POST limits, tracing JIT with a 64 MB buffer, and a 128 MB APCu segment.

Note

The database backends that run on SQLite (Cloudflare D1 and Turso, through the [WordPress SQLite Anywhere](https://github.com/Avunu/wordpress-sqlite-anywhere) plugin) require PHP 8.5. The module asserts this at evaluation time. Plain MySQL or MariaDB sites can stay on 8.2 to 8.4.

## Deploy on NixOS

Add the flake as an input and import its module:

```
<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">inputs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">wordpress-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">url</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">"github:Avunu/wordpress-nix"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

Then, in your host configuration:

```
<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">imports</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:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">wordpress-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">nixosModules</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">default</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ];</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

Pass `inputs` into your modules the way you normally do (for example through `specialArgs`). Import the module through the flake's `nixosModules`, not by file path: only the flake wiring injects the pieces the SQLite backends and gitium need.

The module has three source modes. You pick one with `services.wordpress-nix.source.type`.

| Mode              | Core and `wp-content`                                                     | Best for                                                        |
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `state` (default) | Real, writable files under the state directory                            | Server-specific sites that an admin manages from wp-admin       |
| `git`             | A read-only store path you provide                                        | Sites whose code lives in a repository                          |
| `managed`         | Pinned core from the store, writable `wp-content` seeded from a site repo | The admin half of a split-plane site (not covered further here) |

### State mode: a mutable site

In state mode the core lives in `/var/lib/wordpress/www` and the module downloads it on first boot with `wp core download`. An administrator can then update core, plugins and themes from wp-admin as on any ordinary host.

```
<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">imports</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:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">wordpress-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">nixosModules</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">default</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">services</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">wordpress-nix</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:#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">php</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:#FFA657;--shiki-light:#953800">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">php84</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">domain</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">"blog.example.com"</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">acmeEmail</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">"admin@example.com"</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">source</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">type</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">"state"</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">database</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">createLocally</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:#E6EDF3;--shiki-light:#1F2328">}</span>
```

`source.version` selects the core release to download. It defaults to `latest`.

`database.createLocally = true` enables a local MariaDB with passwordless `unix_socket` authentication. It is off by default, so without it you must point `database.host` at an external server.

The module does not run the WordPress installer. Finish the install in a browser or with wp-cli.

### Git mode: a source-managed site

In git mode the document root is a flake input, a full WordPress webroot (or a Bedrock or Composer layout). The module mounts it read-only and keeps only `wp-content/uploads`, `cache` and `upgrade` writable in state.

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># flake input:  mysite.url = "git+ssh://git@git.example.com/example/mysite";</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">imports</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:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">wordpress-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">nixosModules</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">default</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">services</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">wordpress-nix</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:#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">php</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:#FFA657;--shiki-light:#953800">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">php83</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">domain</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">"shop.example.com"</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">acmeEmail</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">"admin@example.com"</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">source</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:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">type</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">"git"</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">path</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:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">mysite</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># manageWpConfig = false;  # set this if the repository ships its own wp-config.php</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">database</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:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">createLocally</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">false</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">host</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">"db.example.com"</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">name</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">"shop"</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">user</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">"shop"</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">passwordFile</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:#FFA657;--shiki-light:#953800">config</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">age</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">secrets</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">wp-db</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">path</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;  </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># for example an agenix secret</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

What changes compared with state mode:

The module sets `DISALLOW_FILE_MODS`, so wp-admin cannot install plugins or themes. You change code in the repository and redeploy.

The module generates `wp-config.php` into a store copy of your tree, because PHP resolves the symlinks and `ABSPATH` lands in the store. Set `manageWpConfig = false` only if your repository carries its own.

The module copies the platform mu-plugins only in state and managed modes. A git-mode tree has to arrive complete. If you start from a plain checkout, build the tree with `lib.mkSiteDocroot { inherit pkgs; wpContent = "${siteRepo}/wp-content"; }`, which composes the pinned core, your `wp-content` and the platform mu-plugins.

To graft extra plugins or themes onto a base tree, use `lib.mkWordPressSite`.

### What the module sets up

When you enable the service, you get:

**A system user and group** named `wordpress`, with the state directory `/var/lib/wordpress` (change it with `stateDir`).

**`wordpress-init`**, a oneshot unit that prepares the document root, installs the platform mu-plugins (state and managed modes) and the database drop-in (remote SQLite backends), and writes the secrets file.

**`wordpress`**, the FrankenPHP service. It runs Caddy with the `php_server` directive, compresses with `br`, `zstd` and `gzip`, and restarts automatically if it exits.

**`wordpress-cron`** and a timer that runs `wp cron event run --due-now` every minute. WordPress's own cron is disabled with `DISABLE_WP_CRON`. Set `cron.enable = false` to turn the timer off.

**A local MariaDB** with the database and user created, when `database.createLocally` is on.

**A `wp` command** on the system PATH, pointed at the right document root.

**Firewall rules** for port 80, and for 443 over TCP and UDP when `domain` is set. Set `openFirewall = false` to manage this yourself.

A few behaviors worth knowing:

Leave `domain` empty and Caddy binds only `:80`, which suits a setup where something else terminates TLS. Setting `domain` requires `acmeEmail` and turns on automatic HTTPS.

Set `socketPath` (inside its own directory such as `/run/wordpress/`) to serve over a unix socket with no network listener. It cannot be combined with `domain`.

Secrets never enter the Nix store. The database password and the authentication salts are written to `/var/lib/wordpress/wp-secrets.php` with mode `0600` at activation. Salts are generated once, or read from `saltsFile` if you provide one. An external database password comes from `database.passwordFile` through systemd `LoadCredential`.

A local database uses `unix_socket` authentication, so `database.user` must equal `user` (both `wordpress` by default).

The services run with `ProtectSystem=strict`, `PrivateTmp` and `NoNewPrivileges`. The module deliberately does not set `MemoryDenyWriteExecute`, because the opcache JIT would crash FrankenPHP at startup.

### Operating the site

Run wp-cli as the service user:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">sudo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-u</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wp</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">plugin</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">list</span>
```

Every unit writes to journald with `APP_SITE` and `APP_SERVICE` fields (`web`, `init`, `cron`, `db`), so you can filter one site:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">journalctl</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">APP_SITE=blog.example.com</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">APP_SERVICE=web</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-o</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">json</span>
```

`logging.accessLog` (on by default) adds one JSON line per request. Set `logging.site` to change the `APP_SITE` value, which defaults to `domain` or `wordpress`.

### Common options

| Option                   | Default                  | Purpose                                                 |
| ------------------------ | ------------------------ | ------------------------------------------------------- |
| `php`                    | `pkgs.php83`             | Base PHP interpreter, wrapped with the ZTS build        |
| `phpOptimize`            | `true`                   | Clang, LTO and CPU-baseline optimization pass           |
| `phpIniExtra`            | empty                    | Extra `php.ini` lines, applied after `conf/php.ini`     |
| `domain`, `acmeEmail`    | empty                    | Public hostname and ACME contact                        |
| `source.type`            | `state`                  | `state`, `git` or `managed`                             |
| `source.path`            | `null`                   | Document root for git mode                              |
| `database.type`          | `mysql`                  | `mysql`, `d1` or `turso`                                |
| `database.createLocally` | `false`                  | Create a local MariaDB                                  |
| `tablePrefix`            | `wp_`                    | WordPress table prefix                                  |
| `configExtra`            | empty                    | Extra PHP appended to the generated `wp-config.php`     |
| `debug`                  | `false`                  | Turns on `WP_DEBUG` and PHP `display_errors`            |
| `muPlugins`              | the flake's `mu-plugins` | Mu-plugin directories copied in state and managed modes |

The generated `wp-config.php` also sets `WP_MEMORY_LIMIT` to 1G, five post revisions, a seven-day trash, `FS_METHOD` to `direct` and `DISALLOW_FILE_EDIT`. Use `configExtra` for anything site-specific, and keep secrets out of it.

## Build the OCI image

Build an image for a PHP version and load it into Docker:

```
<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">.#wordpress-php83</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>
```

The flake also provides `wordpress-php82`, `wordpress-php84`, `wordpress-php85` and `wordpress-d1-php85`. The D1 variant bundles the SQLite Anywhere plugin and its native extensions. Each image loads as `<imageName>:latest`.

On pushes to `main`, the repository's workflow publishes these to `ghcr.io/avunu/wordpress-nix` with tags such as `php83`, `php85` and `d1-php85`, and aliases `latest` (PHP 8.3) and `d1`.

Core is baked into the image at build time. On first start the entrypoint copies it into `/var/www/html` (it does not download anything) and exits with an error if the image has no baked core. Some older text in the repository mentions `WORDPRESS_SOURCE_URL`, but the entrypoint no longer uses it.

For a site, build from your own flake with `lib.mkSiteImage` (or `nix build .#image` when you use the devenv module). It takes `wpContent`, optional `plugins` and `themes` attribute sets, and defaults to PHP 8.5 with the D1 driver stack included.

### Configure the container

The image listens on port 80, serves `/var/www/html` and reads its configuration from environment variables:

| Variable                                                                               | Purpose                                                                                                 |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `WORDPRESS_HOME`, `WORDPRESS_SITE_URL`                                                 | Site URLs                                                                                               |
| `WORDPRESS_DB_HOST`, `WORDPRESS_DB_USER`, `WORDPRESS_DB_PASSWORD`, `WORDPRESS_DB_NAME` | Database connection                                                                                     |
| `WORDPRESS_TABLE_PREFIX`                                                               | Table prefix                                                                                            |
| `WORDPRESS_SALTS`                                                                      | Eight `define(...)` lines. Generated locally if unset, which is fine for development only               |
| `WORDPRESS_DEBUG`                                                                      | Any non-empty value turns on `WP_DEBUG`, including the string `false`. Leave it unset to keep debug off |
| `WORDPRESS_CONFIG_EXTRA`                                                               | PHP evaluated inside `wp-config.php`                                                                    |
| `WPCONF_<NAME>`                                                                        | Defines the constant `<NAME>`. The values `true` and `false` become booleans                            |
| `WORDPRESS_OBJECT_CACHE`                                                               | Set to `none` to skip the APCu object cache drop-in                                                     |
| `PROC_TYPE`                                                                            | Set to `worker` to run a wp-cron loop every 60 seconds instead of serving web traffic                   |

Warning

The default database password in the image's `wp-config.php` is `wordpress`. Always set `WORDPRESS_DB_PASSWORD` explicitly, and set `WORDPRESS_SALTS` in production.

A minimal Compose file for local testing, adapted from `scripts/docker-compose.yml`:

```
<span style="--shiki-dark:#7EE787;--shiki-light:#116329">services</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">wordpress</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">image</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress-php83:latest</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">ports</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      - </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"8080:80"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">volumes</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      - </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">./wordpress:/var/www/html</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">environment</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_HOME</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">http://localhost:8080</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_SITE_URL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">http://localhost:8080</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_HOST</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_USER</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069"><DB_PASSWORD></span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_NAME</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">depends_on</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      - </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">worker</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">image</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress-php83:latest</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">volumes</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      - </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">./wordpress:/var/www/html</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">environment</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">PROC_TYPE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">worker</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_HOST</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_USER</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069"><DB_PASSWORD></span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">WORDPRESS_DB_NAME</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">depends_on</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      - </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">image</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">mysql:latest</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">environment</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">MYSQL_ROOT_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069"><ROOT_PASSWORD></span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">MYSQL_DATABASE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">MYSQL_USER</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">wordpress</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">MYSQL_PASSWORD</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069"><DB_PASSWORD></span>
```

Note

The worker loop calls `wp cron event run --all --due-now`. The NixOS module's source records that wp-cli rejects `--all` and `--due-now` together, so we did not verify the container worker mode. Check its logs on first use, or run cron from outside the container.

The repository's `scripts/test.sh` runs `nix build`, loads the image and starts its own Compose file, which you can then open at `http://localhost:8080`.

## Develop locally with devenv

A site repository imports `flakeModules.default`, which provides a [devenv](https://devenv.sh) shell that runs the site the way production does. A site flake looks like this:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">outputs</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"> { self</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">,</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> wordpress-nix</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">}@inputs:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">wordpress-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">lib</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">mkFlake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> { </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">inherit</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">inputs</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:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">imports</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:#FFA657;--shiki-light:#953800">wordpress-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">flakeModules</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">default</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">systems</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">"x86_64-linux"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"aarch64-linux"</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">perSystem</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">wordpress-nix</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:#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">siteName</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">"example"</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">siteRoot</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">./.</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">database</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">type</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">"sqlite"</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">configExtra</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">''</span>
<span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">        define('WP_MEMORY_LIMIT', '512M');</span>
<span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">      ''</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</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>
```

`lib.mkFlake` merges wordpress-nix's own inputs under yours, so the site flake only declares `wordpress-nix` (plus a `nixpkgs` input that follows it).

### Start the site

Enter the shell and start the processes:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">allow</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">devenv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">up</span>
```

Without direnv, use `nix develop --impure` instead of `direnv allow`. The shell gives you PHP, FrankenPHP, wp-cli, Mailpit, the migration tools and these commands:

| Command                | What it does                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `devenv up`            | Starts FrankenPHP (plus Mailpit, and `tursodb` or MariaDB when selected). `devenv up -D` runs it detached |
| `wp-stop`              | Stops what `devenv up -D` started                                                                         |
| `wp`                   | Runs wp-cli against the dev site                                                                          |
| `wp-import <FILE>`     | Loads a `.sql`, `.sql.gz` or SQLite file into the dev database (`sqlite` and `turso` types)               |
| `wp-admin-user [NAME]` | Creates or resets a local administrator (default name `dev`) and prints a random password                 |
| `wp-reset`             | Deletes the dev database and replica, and keeps `wp-content`                                              |
| `wp-core-reset`        | Re-seeds core from the platform's pinned version                                                          |

The site listens on `127.0.0.1` on a port from 8100 to 8999, hashed from `siteName`, so every clone of a site gets the same port. Set `port` to pick one yourself. Mail goes to Mailpit instead of out to the internet.

### How the dev shell is laid out

Core is seeded once as real, writable files under `.devenv/state/wordpress/www`. After that, wp-admin and wp-cli can update it, and `wp-core-reset` re-pins it.

`wp-content` is your checkout's own directory, symlinked into that docroot. The shell copies the platform mu-plugins and the `db.php` drop-in into it, and your site repository should gitignore both.

The generated `wp-config.php` sets `WP_ENVIRONMENT_TYPE` to `development`, turns on `WP_DEBUG` with logging to a file under the state directory, and disables WordPress cron and core auto-updates.

Plugins that misbehave on a development machine (security scanners, anti-spam, CAPTCHA gates) stay inactive without touching the database. The `productionOnlyPlugins` option lists them.

Secrets never go in `configExtra`. Constants named in `environmentConstants` are defined from environment variables of the same name, which you can keep in a gitignored `.env`.

### Choose the dev database

| `database.type`    | What runs                                                            |
| ------------------ | -------------------------------------------------------------------- |
| `sqlite` (default) | A SQLite file under `.devenv/state/`, no server                      |
| `turso`            | A local `tursodb`, read through an embedded replica as in production |
| `mysql`            | devenv's MariaDB                                                     |

With `mysql`, `wp-import` does not load the dump for you. Restore it with the `mysql` client against the dev socket instead. The dev shell defaults to PHP 8.5, as the SQLite-based engines require, and we did not verify it on older PHP versions. Other site options include `mailpit.enable`, `muPlugins`, `extraDevPackages` and `extraScripts`. The same options build `packages.image`, `static-assets` and `worker` for the site.

## Bootstrap a site repository

You do not need to write the site flake by hand. Run the bootstrapper in a directory:

```
<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">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/wordpress-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--dry-run</span>
```

It inspects the directory and acts accordingly:

**Empty directory.** It scaffolds a new site from `templates/site`.

**Existing WordPress install.** It adopts it in place: `wp-content/` becomes the payload, and core, `wp-config.php`, uploads and SQL dumps are gitignored. It does not move or delete anything.

**Existing wordpress-nix site.** It reconciles it, adding what is missing without rewriting files you own.

Drop `--dry-run` to apply the plan. Useful flags are `--name <SITE_NAME>`, `--database sqlite|turso|mysql`, `--commit` (otherwise changes are only staged), `--skip-lock` and `--force`. The bare template is also available with `nix flake init -t github:Avunu/wordpress-nix#site`.

Note

The scaffolded flake and its CI callers include Cloudflare identity placeholders marked `CHANGEME`. You do not need to fill them in to develop locally.

## Related documents

[WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/), for the platform mu-plugins and auditing a dump before you restore it.

[WordPress Cron](/kb/wordpress/wordpress-cron/) and [wp-config Reference](/kb/wordpress/wp-config-reference/), for background on the cron and configuration constants the module sets for you.

[WordPress](/kb/wordpress/), for administration topics that apply regardless of how the site is hosted.

[Why Nix for Business Systems](/kb/nixos/why-nix-for-business-systems/), for when this approach is and is not a good fit.

[Reference Architecture for Self-Hosting Business Systems](/kb/nixos/reference-architecture-for-self-hosting-business-systems/), for a hosting pattern built around per-site containers and tunnels.

Sources

- [github.com/Avunu/wordpress-nix](https://github.com/Avunu/wordpress-nix)
- [github.com/Avunu/wordpress-sqlite-anywhere](https://github.com/Avunu/wordpress-sqlite-anywhere)
- [frankenphp.dev](https://frankenphp.dev/)
- [devenv.sh](https://devenv.sh)

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/)

[← PreviousRun Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)[Next →Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)

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 pieces fit](#how-the-pieces-fit)
- [The PHP build](#the-php-build)
- [Deploy on NixOS](#deploy-on-nixos)
- [State mode: a mutable site](#state-mode-a-mutable-site)
- [Git mode: a source-managed site](#git-mode-a-source-managed-site)
- [What the module sets up](#what-the-module-sets-up)
- [Operating the site](#operating-the-site)
- [Common options](#common-options)
- [Build the OCI image](#build-the-oci-image)
- [Configure the container](#configure-the-container)
- [Develop locally with devenv](#develop-locally-with-devenv)
- [Start the site](#start-the-site)
- [How the dev shell is laid out](#how-the-dev-shell-is-laid-out)
- [Choose the dev database](#choose-the-dev-database)
- [Bootstrap a site repository](#bootstrap-a-site-repository)
- [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/)
