Self-host BookStack on a managed VPS: your documentation, on your server

What BookStack does

BookStack is a documentation platform designed to stay simple: its README aims for an experience anyone can pick up with basic word-processing skills. Your teams write their procedures, documentation and knowledge base in a browser, in the language each person prefers.

• Four levels of organization: shelves group books, books hold chapters and pages, chapters are optional, and the content lives in pages.
• Two editors: a visual editor by default and a Markdown editor with live preview, plus diagrams.net drawings.
• Search: within a book, or across all books, chapters and pages.
• Access rights: system-wide roles, and permissions specific to a shelf, book, chapter or page.
• Sign-in: email and password, OpenID Connect, SAML 2.0 and LDAP, with multi-factor authentication through an authenticator app or backup codes, which can be enforced per role.
• History and exchange: page revision history, a REST API, and export to HTML, PDF, plain text, Markdown or portable ZIP.

The project stands by its choices: its README states that BookStack is not designed as an extensible platform for other purposes, and it stays focused on documentation. PDF rendering goes through dompdf, with nothing extra to install and limited capabilities; the project documents other engines through EXPORT_PDF_COMMAND.

What the MIT licence allows

BookStack is published under the MIT licence by Dan Brown and the project’s contributors. It allows any use, modification and distribution, on one condition: keep the copyright notice and the licence text in every copy of the software. The project’s FAQ explains that this attribution applies to the code you share: nothing requires you to show the BookStack name or logo on your instance.

The project maintains a single version, free in both senses: it offers no enterprise edition, and it has no official hosting service and no plans for one. It does sell support plans, which help fund it alongside donations and sponsorships. So BookStack installs on your server, with no licence to buy.

BookStack requirements

Docker stays optional. The project publishes no official image: container setups come from community projects, LinuxServer.io and solidnerd. This guide follows the official path, PHP and MySQL directly on the server, which needs nothing more.

The documentation rules out shared PHP hosting: BookStack needs a server you administer. It gives no figures for memory or processor. On a Managed VPS, describe your usage to us, the number of people and the volume of images and attachments, and we will recommend the right size.

Installing BookStack

The project offers two paths: a script for Ubuntu, the shortest on a new server, and a manual installation for every other case.

With the project’s script, on a brand-new Ubuntu system

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

These scripts are meant for a freshly installed system only: they can overwrite an existing web setup. They also leave out two topics, mail settings and system security, to plan for separately.

The script places BookStack in /var/www/bookstack. The Ubuntu 26.04 script asks for the domain and the admin account’s email address, then displays a randomly generated password at the end, which stays out of its log: write it down. With another script, note the access details shown at the end and change any default credentials at first sign-in.

By hand, on any other machine

Start with the database: one database, and a user limited to it. The project’s script does it this way, with the password of your choice in place of change-me:

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Then fetch the release branch, set the permissions the documentation gives for /var/www/bookstack, and install the dependencies:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Fill in the database and the address in .env:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Finally, point the web root at the public folder: DocumentRoot on Apache, root on Nginx. Without Apache, or when .htaccess files are disabled, add the URL rewrite rules: the project publishes examples for Apache and for Nginx.

A manual installation opens with the account admin@admin.com and the password password. Change the address and the password at first sign-in.

HTTPS and APP_URL

Visitors arrive on ports 80 and 443, under the server’s domain name. Create A and AAAA records for that name, then request the certificate: the Ubuntu 26.04 script sets up Apache on port 80 only, and the installation page leaves HTTPS in your hands. Certbot installs the Let’s Encrypt certificate, adapts Apache and renews the certificate on its own. On Nginx, replace --apache with --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Then switch the address to HTTPS in .env. APP_URL must match the address people visit exactly, prefix included: a mismatch shows up as missing styles, oversized icons and broken menus. An https address turns on secure cookies by itself.

APP_URL=https://docs.example.com

If pages already exist, their links keep the old address in the database. Back up the database, then run the project’s command:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack is served at the root of a domain or subdomain, and the documentation also describes an installation under a subfolder, such as example.com/bookstack. If a reverse proxy goes in front of Apache, declare its address in APP_PROXIES: without it, the audit log and rate limiting see the proxy’s address instead of the visitors’. The documentation keeps APP_PROXIES="*" for debugging.

Where your data lives

Keep the same APP_KEY over time and back it up. BookStack uses it to encrypt, among other things, multi-factor authentication secrets: changing it can break those features, and since version 26.09 the application returns an error if it is missing.

Images are public by default

With the default storage, the web server serves images directly, which is fast, and anyone who knows their address can open them. For internal documentation, the choice is made in STORAGE_TYPE:

For large files, three settings work together: FILE_UPLOAD_SIZE_LIMIT in .env, post_max_size and upload_max_filesize in php.ini, and client_max_body_size on Nginx, which defaults to 1 MB.

Two more settings matter for living documentation: each page keeps 100 revisions by default (REVISION_LIMIT), and the recycle bin holds deleted items for 30 days (RECYCLE_BIN_LIFETIME).

Email: SMTP and the queue

BookStack sends email for address confirmation, forgotten passwords, invitations and notifications. From a Simafri VPS, sending goes through an authenticated SMTP relay on port 587: the address of a mail account you already have, or Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Check the result in "Settings", "Maintenance", with the "Send a Test Email" action, which displays any errors it meets. A failed invitation shows on screen, while a failed notification stays in the application log.

Sending in the background

By default, BookStack sends email and webhooks during the request, which can slow pages down. To move them to the background, write QUEUE_CONNECTION=database in .env and run a service, using the example the documentation gives for a script-based Ubuntu installation:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Securing your BookStack instance

The security documentation gives a list to work through right after installation:

1. Change the first administrator’s address and password.
2. Check that the web server serves only the public folder, especially if BookStack lives under /var/www.
3. Limit the database user to the BookStack database alone.
4. Set APP_URL, so that system-generated addresses cannot be manipulated.
5. Review the registration and public access settings, then the roles.

Multi-factor authentication can then be enforced per role. Also sign up for the project’s security mailing list to receive its alerts. The /status address is there for monitoring: it answers 200 when all is well, and an error code of 400 or higher otherwise.

PHP matters as much as BookStack. On October 21, 2026, the project published an alert about a critical PHP security update, fixed in 8.5.12, 8.4.27, 8.3.36 and 8.2.35. Ubuntu ships these fixes under its own package numbers, such as 8.3.6-0ubuntu0.24.04.13 for Ubuntu 24.04.

For your content, keep the default filtering on, and loosen it only on instances where nobody but trusted people write. If an admin account is lost, php artisan bookstack:create-admin creates another one, and php artisan bookstack:reset-mfa removes a user’s multi-factor authentication.

Backups and updates

A complete backup brings together the database and the four file locations specific to your instance. Content exports serve another purpose: the documentation states that they do not replace a backup.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

The first line suits a script-based installation, where the MySQL root user connects through sudo; elsewhere, write mysqldump -u bookstack -p bookstack. Store both files separately, preferably on another machine. The archive contains .env, and so APP_KEY and your passwords: treat it as a secret.

Restoring

On a new machine, install BookStack without running php artisan migrate, a step to comment out in the script if you use it, then restore the database and the files, keeping the original APP_KEY:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

If the installed version is newer than the backup, then run php artisan migrate. Restore the web server’s write permissions on the restored folders. If the address has changed, correct APP_URL and run bookstack:update-url.

Updating

Back up the database and the files before each update, then, from the BookStack folder:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

The Ubuntu 26.04 script installs BookStack without Composer. For that case, the updates page offers, in beta, ./bookstack-system-cli download-vendor in place of composer install --no-dev. The same tool can back up and restore, but the project does not yet consider it production-ready: test it before relying on it.

The documentation keeps a list of instructions specific to each version, to read for the version you are moving to. A few examples:

• Version 26.09: APP_KEY becomes mandatory.
• Version 26.05: the storage/fonts folder must stay writable by the web server, or PDF exports may fail.
• Version 26.03: try sending email after the update.
• Version 25.11: major database changes, whose migration can take several minutes on a large instance.

Vulnerabilities are fixed in maintenance releases, such as 26.09.3 of November 11, 2026: images and drawings on a draft or trashed page remained accessible and editable, and an editor's personal draft could become visible to other people.

Who does what on a Managed VPS

Self-hosting means running the server on top of the application. On a Managed VPS, our teams take the server in hand and proactively monitor your instance; BookStack remains your software, with its settings and its data.

If you would rather have our teams work inside the application itself, that service is billed hourly or at a fixed price, with a quote given before the work begins.