Self-host BookStack on a VPS

To install BookStack, clone its release branch, run Composer, point a web server running PHP 8.2 or later at its public folder, and give it a MariaDB or MySQL database. On VPSNine the BookStack one-click app does all of that on the first boot, replaces the default admin login with a generated password, and adds your domain and HTTPS with one command.

BookStack organises documentation into shelves, books, chapters and pages, with a WYSIWYG or Markdown editor that non-technical people can use.

What you need#

• The Budget plan (2 GB) runs BookStack and MariaDB for a small team. Choose Standard for many editors or large uploads; MariaDB is usually the first thing to want more memory.
• Ubuntu 24.04 or 26.04, or Debian 12 or 13. BookStack needs PHP 8.2 or later, and Ubuntu 22.04 ships 8.1, so the app isn't offered there. It isn't offered on AlmaLinux, Rocky Linux or Fedora either, where PHP would have to come from outside the default repositories.
• A domain or subdomain for it, like docs.example.com, when you're ready for HTTPS.

Install it with the one-click app#

Order a server with the BookStack app. We install it as BookStack's guide describes, in /var/www/bookstack, served by nginx and PHP-FPM, with MariaDB on localhost. BookStack's setup creates admin@admin.com with the password password; the installer replaces that with a generated password before nginx serves the site, so the default login never works. One-click apps shows how to follow the install.

When it's done:

1. Show your login and open the site by its address, for example http://203.0.113.10/:

   bash

   cat /root/bookstack-admin.txt

2. In My Account, change the admin's email (it starts as admin@example.com) and name, and turn on multi-factor authentication.

3. Point a domain at the server and run vps9-https docs.example.com, as below.

The database password is in /root/bookstack-db.txt. Registration is off, so only people you add can log in.

Until you add HTTPS, your password crosses the network unencrypted. Do step 3 soon.

Put it on your domain with HTTPS#

BookStack's vps9-https uses nginx and Certbot rather than Caddy. First point the domain's A record at the server, and make sure ports 80 and 443 are allowed if you use the panel firewall. Then:

vps9-https docs.example.com

It does four things:

1. Sets the domain as nginx's server_name for the site.
2. Runs certbot --nginx -d docs.example.com, which gets a Let's Encrypt certificate and adds it to nginx. Certbot asks for your email address and to accept its terms, so run it in an SSH session you can type into.
3. Dumps the database to /root/bookstack-before-url-change-<date>.sql.
4. Runs php artisan bookstack:update-url to move the links stored in your pages to https://docs.example.com, sets APP_URL in .env, and clears BookStack's caches.

To move to another domain later, run it again with the new one. Serve a site with nginx and HTTPS explains how the certificate side works.

Doing it by hand on another server#

BookStack's installation guide lists the requirements: PHP 8.2 or newer with its common extensions, MySQL 8.0 or MariaDB 10.6 or newer, Git and Composer. The outline:

1. Clone the release branch and install its dependencies:

   bash

   git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch /var/www/bookstack
   cd /var/www/bookstack
   composer install --no-dev

2. Copy .env.example to .env, and fill in APP_URL, the database details and your mail settings.

3. Make storage, bootstrap/cache and public/uploads writable by the web server.

4. Run php artisan key:generate, then php artisan migrate.

5. Point the web server's root at the public folder, with rewrite rules if you're not on Apache.

6. Log in as admin@admin.com with the password password and change both straight away, before anyone else finds the site.

BookStack also publishes install scripts for fresh Ubuntu servers, using Apache and MySQL. They can overwrite an existing web setup, so use them only on a new server.

Updates and backups#

We turn on automatic security updates for the system (security fixes only, no automatic reboot), and PHP-FPM restarts when an update replaces code it runs. Check and patch PHP on your VPS shows how to confirm PHP is up to date.

BookStack itself is yours to update. Back up first, then follow its update guide:

cd /var/www/bookstack
git pull origin release
composer install --no-dev
php artisan migrate

Back up the database and the files that aren't in Git, and copy them off the server:

mariadb-dump bookstack > /root/bookstack-$(date +%F).sql
cd /var/www/bookstack
tar czf /root/bookstack-files-$(date +%F).tgz .env public/uploads storage/uploads themes

.env holds the application key and database password, so treat the archive like a password. Backups you should run shows how to copy them off nightly.

When it goes wrong#

• Certbot stops at a prompt or fails: it asks for an email address and for you to accept the terms, so vps9-https needs an interactive SSH session. If it can't get a certificate, the domain doesn't point at the server yet, or port 80 is closed.
• Links and images point at the old address after a domain change: APP_URL and the links stored in pages still use it. Run vps9-https with the new domain, which does both. If you changed the domain by hand, run php artisan bookstack:update-url https://old.example.com https://docs.example.com in /var/www/bookstack, update APP_URL in .env, then php artisan cache:clear.
• The install stopped saying BookStack needs PHP 8.2: the server runs a system with older PHP, such as Ubuntu 22.04. Reinstall with Ubuntu 24.04 or Debian 12 or later.