Admin Documentation

While we try to ensure a fairly steady & stable path for BookStack updates, requirements do change as software develops & moves on. In particular, the minimum required version of PHP will increase about once per year. Every so often we also may require a new minimum version of composer to be used for BookStack. This page details the common steps required to update these both.

When building up a documentation store, or assessing platform options, it can be useful to understand how data is stored so you know how portable & accessible your content is. This page aims to clearly lay-out how content is stored within BookStack and what our general project aims are when it comes to data storage, content formats, and how these may lead design & development decisions.

The BookStack System CLI allows easy running of BookStack infrastructure-level tasks such as backing up, restoring or updating. The CLI is distributed with the BookStack project source code, although the CLI is self-contained and can run independently of a BookStack instance.

BookStack requires the ability to write and read files for various uses such as writing logs, handling file uploads and running application code. Ideally, files permissions should be limited to just what’s required to reduce the chance of potential vulnerability exploit.

Within BookStack email is used in various ways relating to user management & authentication. Outgoing webhooks are available as a mechanism to extend BookStack or notify in an event-driven manner.

OpenID Connect (OIDC) can be used within BookStack as a primary method of authentication. This replaces the default email & password authentication mechanism. BookStack supports a simple level of auto-discovery to ease endpoint and key management.

Sometimes you may want to perform deeper customisation to BookStack or extend the system to suit your use-case. The core of BookStack is fairly rigid as it’s intended to be a configured, ready-to-use system out of the box but there are a few advanced options for performing more advanced modifications without needing to alter the system code-base.

BookStack can be configured to utilise a SAML 2.0 based authentication provider as a solution for users to log-in, log-out and self-register within BookStack. This replaces the default email & password authentication mechanism within BookStack. When enabled, BookStack will attempt to match the SAML user to an existing BookStack user based on a stored external id attribute otherwise, if not found, BookStack will effectively auto-register that user to provide a seamless access experience.

You may want to host BookStack on a “Subdirectory” of your website, For example https://example.com/bookstack. To achieve this you will need to make some alterations to your webserver config. The details for setting this up on Apache or Nginx can be found below. You’ll need to follow the BookStack setup section after configuring any webserver.

By default the BookStack interface is shown in English. Additional languages are supported by the wider BookStack community. English translations may show as a fallback if a chosen alternative language does not have fully up-to-date translations.

BookStack allows users to upload both images for content and files as attachments.

For information relating to security for file uploads please refer to the Security Page.

• .env Options
• Revision Limit
• Recycle Bin Lifetime
• Custom User Avatar Fetching
• Custom diagrams.net URL
• IP Address Storage Precision

.env Options

As part of the installation of BookStack you will have a .env file containing system options. By default this only contains a few options. Within your BookStack install directory you should also have a .env.example.complete file which contains every supported option available alongside the default value for each. You can copy options in this file to your own .env file as required. Many of the options in the .env.example.complete file are detailed in-depth in this documentation.

You may want to customise BookStack to use custom branding, or you may just not like the default blue theme. Customising the branding of BookStack is super simple and can be done within the “Settings > Customization” area of the interface. Here you can change the application name, logo and the core colours used. Additional ways to customise are listed below:

BookStack has some command line actions that can help with maintenance and common operations. There are also many commands available from the underlying Laravel framework. To list all available commands you can simply run php artisan from your BookStack install folder. Custom BookStack commands are all under the ‘bookstack’ namespace.

By default BookStack uses dompdf to export pages as PDF documents. The benefit of using dompdf is that it doesn’t require any additional installation or setup but the rendering capabilities are somewhat limited.

BookStack can be configured to allow LDAP based user login. While LDAP login is enabled you cannot log in with the standard user/password login and new user registration is disabled. BookStack will only use the LDAP server for getting user details and for authentication. Data on the LDAP server is not editable through BookStack.

While BookStack does not currently have a built-in way to backup and restore content, it can usually be done via the command line with relative ease. The below commands are based on using Ubuntu. If you are using a different operating system you may have to alter these commands to suit.

Within BookStack specific data is cached server-side to increase performance in certain areas. Sessions are used for storing visitor-specific details, to allow things such as persisting user logins. Both of these mechanisms have various control options, and both use the local filesystem by default.

When using BookStack, especially when initially setting it up or after updating, you may come across some errors. While we try to reduce these as much as possible and make them helpful sometimes you may come across a bland “An error has occurred” message. This is to prevent any potentially sensitive information being shown to all users.

Below you can find details on how to install BookStack on your own hosting. There are a number of installation options available depending on your setup. The install process will require some knowledge of hosting a PHP web application & database.

Currently BookStack does not support multiple instances from one installation but you can set up multiple instances on the same server by creating multiple installations and configuring your web-server appropriately.

Since BookStack can hold important information for users you should be aware of any potential security concerns. Read through the below to ensure you have secured your BookStack instance. Note, The below only relates to BookStack itself. The security of the server BookStack is hosted on is not instructed below but should be taken into account.

BookStack currently supports login via a range of third party and social applications. Once enabled options for these services will show up in the login, registration and user profile pages. By default these services are disabled. To enable them you will have to create an application on the external services to obtain the required application credentials.

BookStack is updated regularly. We try our best to keep the platform and upgrade path as stable as possible. The latest release can be found on GitHub here and detailed information on releases is posted on the BookStack blog here.

As of BookStack v0.17 UTF8mb4 is the default database charset and collation which allows emoji support. If you installed and used BookStack prior to v0.17 you will have to upgrade your database manually to support emoji.