# Self-host BookStack on a VPS

> Install BookStack, the documentation wiki, on nginx, PHP and MariaDB, replace its default admin login, then move it to your domain with HTTPS.

Source: https://vpsnine.com/help/self-host-bookstack · Updated: 2026-10-21

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](https://vpsnine.com/apps/bookstack). 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](https://vpsnine.com/help/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](https://vpsnine.com/help/server-firewall). Then:

```bash
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](https://vpsnine.com/help/nginx-and-https) explains how the certificate side works.

## Doing it by hand on another server

BookStack's [installation guide](https://www.bookstackapp.com/docs/admin/installation/) 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](https://vpsnine.com/help/php2shell-check-and-patch-php) shows how to confirm PHP is up to date.

BookStack itself is yours to update. Back up first, then follow its [update guide](https://www.bookstackapp.com/docs/admin/updates/):

```bash
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:

```bash
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](https://vpsnine.com/help/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.