Official NixOS Wiki

Bookstack: Difference between revisions

← Older edit
VisualWikitext
Klinger (talk | contribs)
trusted
904 edits
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
 
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]]
Retrieved from "https://wiki.nixos.org/wiki/Bookstack"