Bookstack - Revision history

Akonradi: Update configuration for NixOS 25.11 and add troubleshooting tips that helped debug. The new configuration was taken from https://github.com/NixOS/nixpkgs/issues/422234#issuecomment-3035710896

2025-12-04T15:48:15Z

Update configuration for NixOS 25.11 and add troubleshooting tips that helped debug. The new configuration was taken from https://github.com/NixOS/nixpkgs/issues/422234#issuecomment-3035710896

← Older revision		Revision as of 15:48, 4 December 2025
Line 7:		Line 7:

	== Configuration ==		== Configuration ==
	BookStack ~~uses~~ a ~~MySQL (MariaDB) as~~ a ~~DBMS, the service provides an option~~ to ~~create the necessary database with the necessary permissions:<syntaxhighlight lang~~=~~"nixos">~~		BookStack requires some configuration to get working. You'll need to set up a secret and a database to connect to.
	~~services.bookstack.database.createLocally~~ = ~~true; # False by default~~
	~~</syntaxhighlight>BookStack needs to know the domain on which it runs:<syntaxhighlight lang~~=~~"nixos">~~		=== App secret ===
	~~services.bookstack.hostname~~ = ~~"kb.example.com";~~		BookStack requires an app secret, primarily used for encryption. You can generate a valid app key using the following command:<syntaxhighlight lang="bash">
	~~</syntaxhighlight>~~BookStack requires an app secret, primarily used for encryption. You can generate a valid app key using the following command:<syntaxhighlight lang="bash">
	echo base64:$(nix run nixpkgs#openssl -- rand -base64 32)		echo base64:$(nix run nixpkgs#openssl -- rand -base64 32)

	</syntaxhighlight>Write this value to a file owned by the <code>bookstack</code> user in the <code>bookstack</code> group, perhaps using a secret manager such as [[Agenix]], and provide its path to Bookstack:<syntaxhighlight lang="nixos">		</syntaxhighlight>Write this value to a file owned by the <code>bookstack</code> user in the <code>bookstack</code> group, perhaps using a secret manager such as [[Agenix]], and provide its path to Bookstack:<syntaxhighlight lang="nixos">
	services.bookstack.~~appKeyFile~~ = "path-to-your-secret";		services.bookstack.settings.APP_KEY_FILE = "path-to-your-secret";

	</syntaxhighlight>And using [[Agenix]],<syntaxhighlight lang="nixos">		</syntaxhighlight>And using [[Agenix]],<syntaxhighlight lang="nixos">
	services.bookstack.~~appKeyFile~~ = config.age.secrets.bookstack-appkey.path;		services.bookstack.settings.APP_KEY_FILE = config.age.secrets.bookstack-appkey.path;
	</syntaxhighlight>~~To go further, it is useful to know that BookStack uses Laravel. So, for example, to use S3 instead of the local filesystem, check Laravel's documentation on file storage and the service definition.~~		</syntaxhighlight>

			=== Database ===
			BookStack uses a MySQL (MariaDB) as a DBMS. Connection parameters are provided via <code>services.bookstack.settings</code>. To point at a database running locally, your configuration might look like this:<syntaxhighlight lang="nixos">
			services.bookstack.settings.DB_HOST = "localhost";
			services.bookstack.settings.DB_PORT = 3306;
			services.bookstack.settings.DB_USERNAME = "bookstack";
			services.bookstack.settings.DB_DATABASE = "bookstack";
			services.bookstack.settings.DB_SOCKET = "/run/mysqld/mysqld.sock";

			</syntaxhighlight>A locally-running database can be be configured with the following:<syntaxhighlight lang="nixos">
			services.mysql = {
			enable = true;
			package = pkgs.mariadb;
			settings.mysqld.character-set-server = "utf8mb4";
			ensureDatabases = [ "bookstack" ];
			ensureUsers = [{
			name = "bookstack";
			ensurePermissions = {
			"bookstack.*" = "ALL PRIVILEGES";
			};
			}];
			};
			</syntaxhighlight>

			=== Serving ===
			BookStack needs to know the domain on which it runs and the URL used to access it:<syntaxhighlight lang="nixos">
			services.bookstack.hostname = "kb.example.com";
			services.bookstack.settings.APP_URL = "http://kb.example.com";
			</syntaxhighlight>To go further, it is useful to know that BookStack uses Laravel. So, for example, to use S3 instead of the local filesystem, check Laravel's documentation on file storage and the service definition.
	== Tips and tricks ==		== Tips and tricks ==

Line 38:		Line 65:
	You need to connect Bookstack to a MySQL database, the service definition can install and configure one on your system with <code>services.bookstack.database.createLocally = true;</code>, otherwise you need to configure it yourself.		You need to connect Bookstack to a MySQL database, the service definition can install and configure one on your system with <code>services.bookstack.database.createLocally = true;</code>, otherwise you need to configure it yourself.

			=== "An unknown error occurred" when viewing your wiki in a browser ===
			If you set up BookStack with NixOS < 25.11, you might have used an un-prefixed base64-encoded app key. Make sure your app key file contents include the "base64:" prefix.

			=== Logs locations ===
			With the default settings, BookStack logs can be found under <code>/var/lib/bookstack/storage/logs/</code>.
	[[Category:Server]]		[[Category:Server]]
	[[Category:Web Applications]]		[[Category:Web Applications]]

Klinger: Category:Server Category:Web Applications

2025-01-04T10:50:38Z

Category:Server Category:Web Applications

← Older revision		Revision as of 10:50, 4 January 2025
Line 37:		Line 37:
	=== "No such file or directory" in bookstack-setup ===		=== "No such file or directory" in bookstack-setup ===
	You need to connect Bookstack to a MySQL database, the service definition can install and configure one on your system with <code>services.bookstack.database.createLocally = true;</code>, otherwise you need to configure it yourself.		You need to connect Bookstack to a MySQL database, the service definition can install and configure one on your system with <code>services.bookstack.database.createLocally = true;</code>, otherwise you need to configure it yourself.

			[[Category:Server]]
			[[Category:Web Applications]]

Dander: init bookstack

2025-01-04T02:19:53Z

init bookstack

New page

[https://www.bookstackapp.com/ BookStack] is a platform for organising and storing information.

== Installation ==
To install BookStack, add the following to your NixOS configuration:<syntaxhighlight lang="nixos">
services.bookstack.enable = true;
</syntaxhighlight>[https://search.nixos.org/options?channel=unstable&query=services.bookstack More options] are available.

== Configuration ==
BookStack uses a MySQL (MariaDB) as a DBMS, the service provides an option to create the necessary database with the necessary permissions:<syntaxhighlight lang="nixos">
services.bookstack.database.createLocally = true; # False by default
</syntaxhighlight>BookStack needs to know the domain on which it runs:<syntaxhighlight lang="nixos">
services.bookstack.hostname = "kb.example.com";
</syntaxhighlight>BookStack requires an app secret, primarily used for encryption. You can generate a valid app key using the following command:<syntaxhighlight lang="bash">
echo base64:$(nix run nixpkgs#openssl -- rand -base64 32)

</syntaxhighlight>Write this value to a file owned by the <code>bookstack</code> user in the <code>bookstack</code> group, perhaps using a secret manager such as [[Agenix]], and provide its path to Bookstack:<syntaxhighlight lang="nixos">
services.bookstack.appKeyFile = "path-to-your-secret";

</syntaxhighlight>And using [[Agenix]],<syntaxhighlight lang="nixos">
services.bookstack.appKeyFile = config.age.secrets.bookstack-appkey.path;
</syntaxhighlight>To go further, it is useful to know that BookStack uses Laravel. So, for example, to use S3 instead of the local filesystem, check Laravel's documentation on file storage and the service definition.

== Tips and tricks ==

=== Changing the default port Nginx listens on ===
<syntaxhighlight lang="nixos">
services.bookstack.nginx.listen = [
{ addr = "[::]"; port = 8080; ssl = false;}
{ addr = "0.0.0.0"; port = 8080; ssl = false;}
{ addr = "[::]"; port = 8443; ssl = true;}
{ addr = "0.0.0.0"; port = 8443; ssl = true;}
]
</syntaxhighlight>

== Troubleshooting ==

=== "No such file or directory" in bookstack-setup ===
You need to connect Bookstack to a MySQL database, the service definition can install and configure one on your system with <code>services.bookstack.database.createLocally = true;</code>, otherwise you need to configure it yourself.