# Dealing with Bookstack breakage in a NixOS 25.11 upgrade

In 25.11, the NixOS service module for Bookstack unfortunately saw a number of breaking changes that were never added to the release notes.

Here's what you need to fix to get it to work again:

- You need to add a `base64:` prefix to the key in your app key file. The old key generation stored it without this prefix, and then inserted it at runtime. This runtime fix has been removed in a recent refactor of the service module, and so old key files no longer work in 25.11. To fix it, prepend the content in your `APP_KEY_FILE` with `base64:` yourself. Don't forget to deploy your secrets again if you're using a deployment tool, and restart `phpfpm-bookstack` to have the change take effect. See also [this thread](https://github.com/BookStackApp/BookStack/issues/5289).
- You need to configure MySQL (or more likely, MariaDB) yourself, the module no longer does this for you. This may not be necessary if you're upgrading on the same machine, but it'll probably bite you if you ever move to a different machine, so I'd recommend just adding it to your configuration anyway. See the example below.
- You need to specify most of the application settings yourself, as most of the configuration defaults have disappeared. See the example below.

```
		services.bookstack = {
			# ...
			# database = { createLocally = true; }; # No longer works in NixOS 25.11
			settings = {
				APP_KEY_FILE = "/var/lib/bookstack/app-key";
				DB_HOST = "localhost";
				DB_PORT = 3306;
				DB_DATABASE = "bookstack";
				DB_USERNAME = "bookstack";
				SESSION_SECURE_COOKIE = true; # Only set to true when you're serving over TLS (which I hope you are!)
			};
            # ...
		};

		# For Bookstack
		services.mysql = let
			bsConfig = config.services.bookstack.settings;
		in {
			enable = true;
			package = pkgs.mariadb;
			ensureDatabases = [ bsConfig.DB_DATABASE ];
			ensureUsers = [{
				name = bsConfig.DB_USERNAME;
				ensurePermissions = {
					"${bsConfig.DB_DATABASE}.*" = "ALL PRIVILEGES";
				};
			}];
		};
```

The above example **does not include** the mail settings, which have *also* been removed from the defaults. Have a look at [the last pre-breakage version of the module](https://github.com/NixOS/nixpkgs/blob/374e6bcc403e02a35e07b650463c01a52b13a7c8/nixos/modules/services/web-apps/bookstack.nix#L315) if you need to replicate these defaults.