How to Install BookStack on Ubuntu 24.04 — Self-Hosted Team Documentation Wiki

Team knowledge tends to live in a dozen scattered places: Slack threads, random Google Docs, half-finished Notion pages, a retired Confluence space nobody wants to pay for anymore. BookStack fixes that by giving you a simple, opinionated wiki with a clean book/chapter/page structure that matches how engineers actually think about documentation. This tutorial walks you through a production-quality BookStack install on Ubuntu 24.04 from a fresh VPS, including the full LAMP stack, SMTP mail, SSO options, and Let's Encrypt TLS.

Prefer to stay focused on writing docs? Deploy a Starter VPS and have BookStack live on your own domain in under an hour.

Table of Contents

What is BookStack?

BookStack is an open-source, self-hosted documentation platform written in PHP (Laravel). It organizes content in a deliberately simple three-level hierarchy — Shelves > Books > Chapters > Pages — that mirrors how physical documentation is structured. Every page is either written in a WYSIWYG editor or in Markdown, with a full revision history, per-item permissions, drawings via the built-in diagrams.net integration, and global full-text search.

BookStack is MIT-licensed and maintained by Dan Brown and a small, active community. It is used by teams at the BBC, NASA, Mozilla, and thousands of SMBs and homelabs for internal wikis, runbooks, SOPs, customer-facing help centres, and personal knowledge bases. Full feature documentation lives at bookstackapp.com/docs.

Compared to other self-hosted knowledge tools in the vps-server.host guide library — Wiki.js, Outline, DokuWiki, and Trilium — BookStack sits in the sweet spot between "simple enough that non-technical staff will write in it" and "structured enough that the docs don't turn into chaos after six months".

Why Self-Host Your Team Docs Instead of Confluence?

Atlassian moved Confluence to a cloud-only model for most customers and priced Standard at roughly USD 6.40 per user per month. For a 50-person company, that's USD 3,800+ per year for a tool that stores your crown jewels — onboarding docs, architecture diagrams, incident post-mortems, customer intel — on servers you don't control.

Self-hosting BookStack on a single VPS gives you concrete advantages:

• Predictable flat-rate cost — A Starter VPS hosts BookStack for a fixed monthly fee regardless of whether you have 5 editors or 500. No per-seat creep.
• Data sovereignty — Your internal runbooks, security procedures, and customer data never leave your server. This matters for GDPR, SOC 2, HIPAA, and ITAR-adjacent workloads.
• No forced upgrades or feature removal — BookStack versions are yours to pin. You choose when to upgrade, unlike SaaS tools where features disappear overnight.
• Full customization — Theme it with your brand colours, add custom HTML/JS, patch the source, or extend via the REST API. Everything is PHP you can read.
• Works offline and on-prem — Run it on a LAN-only VPS behind a VPN for air-gapped environments.
• No vendor lock-in — Export every page as HTML, PDF, Markdown, or plain text at any time. The database is a standard MariaDB dump.

Prerequisites

Before you start, make sure you have:

• A VPS running Ubuntu 24.04 LTS with root or sudo access
• SSH access (terminal on macOS/Linux, PuTTY on Windows)
• A registered domain (e.g. docs.example.com) with an A record pointing to your VPS public IP
• At least 2 GB of RAM and 10 GB of disk — the Starter plan is sufficient for small-to-medium teams

ssh root@your-server-ip

Step 1: Update the System

Refresh the package index and upgrade everything before adding new software:

sudo apt update && sudo apt upgrade -y

If the kernel was updated, reboot and reconnect:

sudo reboot

Step 2: Install Apache, MariaDB and PHP 8.3

BookStack requires the classic LAMP stack with a specific set of PHP extensions. Ubuntu 24.04 ships PHP 8.3 in its default repositories, which is exactly what current BookStack targets.

Install everything in one go:

sudo apt install -y apache2 mariadb-server \
  php8.3 libapache2-mod-php8.3 \
  php8.3-curl php8.3-mbstring php8.3-ldap php8.3-xml php8.3-zip \
  php8.3-gd php8.3-mysql php8.3-tidy php8.3-bcmath php8.3-intl \
  git unzip

Enable the services to start on boot and start them now:

sudo systemctl enable --now apache2 mariadb

Harden the MariaDB install:

sudo mysql_secure_installation

Accept the defaults for most prompts. When asked, set a strong root password, remove anonymous users, disallow remote root login, and remove the test database.

Enable the Apache rewrite module — BookStack relies on it for clean URLs:

sudo a2enmod rewrite
sudo systemctl restart apache2

Verify PHP:

php -v

Expected output:

PHP 8.3.6 (cli) (built: Apr 15 2024 19:24:08) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.6, Copyright (c) Zend Technologies

Step 3: Create the BookStack Database

Log into MariaDB as root:

sudo mysql -u root -p

Create a dedicated database and user. Replace STRONG_PASSWORD_HERE with a long random string:

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD_HERE';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;
EXIT;

You can generate a password with openssl rand -base64 24 before running the SQL.

Step 4: Install Composer

BookStack uses Composer to manage its PHP dependencies. Install it globally so the composer binary is available everywhere:

cd /tmp
curl -sS https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php

Verify:

composer --version

Expected output (version will vary):

Composer version 2.7.6 2024-04-10 16:04:47

Step 5: Clone BookStack and Install Dependencies

Clone the latest release branch into /var/www/bookstack:

cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack

Install PHP dependencies. Composer must run as a non-root user, so use --no-plugins --no-scripts with sudo or switch users — the cleanest approach is to temporarily allow it and pin ownership after:

sudo composer install --no-dev --no-plugins --no-scripts --optimize-autoloader

Set file ownership so Apache (the www-data user) can read the code and write to the storage and cache directories:

sudo chown -R www-data: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

Step 6: Configure the .env File

BookStack reads its configuration from a .env file at the project root. Copy the example:

sudo -u www-data cp /var/www/bookstack/.env.example /var/www/bookstack/.env

Generate a unique application key — this is used for encrypting cookies and sessions, and must never be shared:

cd /var/www/bookstack
sudo -u www-data php artisan key:generate --force

Now edit the .env file:

sudo -u www-data nano /var/www/bookstack/.env

Set the core values:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=STRONG_PASSWORD_HERE
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

Save and exit. The APP_URL value matters — BookStack uses it to build absolute links in emails and OAuth redirects, so put the full HTTPS URL you'll use, even before TLS is installed.

Step 7: Run Migrations and Seed the Admin User

With the database credentials in place, run the migrations to create all tables:

cd /var/www/bookstack
sudo -u www-data php artisan migrate --force

Expected output (abbreviated):

Migration table created successfully.
Migrating: 2015_07_12_114933_create_users_table
Migrated:  2015_07_12_114933_create_users_table (23.45ms)
Migrating: 2015_07_12_170030_create_books_table
...

The first migration run also seeds a default admin user. Retrieve its credentials:

Default admin account created:
Email:    [email protected]
Password: password

Change these immediately after your first login — or set a custom admin now with:

sudo -u www-data php artisan bookstack:create-admin \
  --email="[email protected]" \
  --name="Site Admin" \
  --password="YOUR_STRONG_ADMIN_PASSWORD"

Cache the config and routes for production performance:

sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache

Step 8: Configure the Apache Virtual Host

Create a dedicated vhost for BookStack. Replace docs.example.com with your actual domain:

sudo tee /etc/apache2/sites-available/bookstack.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName docs.example.com
    DocumentRoot /var/www/bookstack/public
    <Directory /var/www/bookstack/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
        <IfModule mod_rewrite.c>
            <IfModule mod_negotiation.c>
                Options -MultiViews -Indexes
            </IfModule>
            RewriteEngine On
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule ^(.*)/$ /$1 [L,R=301]
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/bookstack-error.log
    CustomLog ${APACHE_LOG_DIR}/bookstack-access.log combined
</VirtualHost>
EOF

Disable the default Apache site, enable the BookStack site, and reload:

sudo a2dissite 000-default.conf
sudo a2ensite bookstack.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

Open your browser to http://docs.example.com — you should see the BookStack login page. Log in with the admin credentials you created in Step 7.

Step 9: Enable HTTPS with Let's Encrypt

Install Certbot with the Apache plugin:

sudo apt install -y certbot python3-certbot-apache

Request a certificate. Certbot will automatically edit your Apache vhost to add the TLS configuration and a redirect from HTTP to HTTPS:

sudo certbot --apache -d docs.example.com

Answer the prompts — supply an email for expiration notices and choose option 2 (redirect all HTTP traffic to HTTPS). Certbot installs a timer to renew certificates automatically 30 days before expiry. Verify the auto-renew is working:

sudo certbot renew --dry-run

Now reload BookStack at https://docs.example.com. Everything should be green-padlocked.

Step 10: Configure SMTP for Outbound Mail

BookStack sends email for new user invitations, password resets, and watch notifications. Configure an SMTP relay by editing .env:

sudo -u www-data nano /var/www/bookstack/.env

For a transactional provider (Postmark, Mailgun, SES, Brevo, etc.), use these values:

MAIL_DRIVER=smtp
MAIL_FROM_NAME="Example Docs"
[email protected]
MAIL_HOST=smtp.postmarkapp.com
MAIL_PORT=587
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls

Rebuild the config cache and send a test mail to yourself:

cd /var/www/bookstack
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan bookstack:test-email [email protected]

If the message arrives, you're done. If not, watch the BookStack log:

sudo tail -f /var/www/bookstack/storage/logs/laravel.log

Common issues are wrong port (465 for SSL, 587 for STARTTLS), missing DNS MX for the sending domain, or firewall rules blocking outbound port 587.

Step 11: Enable SSO (LDAP, SAML, OIDC)

For teams larger than a handful of people, route authentication through your existing identity provider. BookStack supports three enterprise SSO protocols plus a long list of social logins.

LDAP / Active Directory

In .env:

AUTH_METHOD=ldap
LDAP_SERVER=ldaps://dc01.example.com:636
LDAP_BASE_DN=ou=People,dc=example,dc=com
LDAP_DN=cn=bind-user,ou=ServiceAccounts,dc=example,dc=com
LDAP_PASS=bind-user-password
LDAP_USER_FILTER=(&(uid=${user}))
LDAP_VERSION=3
LDAP_TLS_INSECURE=false

The php8.3-ldap extension you installed in Step 2 is the dependency that enables this.

SAML 2.0

Ideal for Okta, Azure AD, OneLogin, and Keycloak:

AUTH_METHOD=saml2
SAML2_NAME=Okta
SAML2_EMAIL_ATTRIBUTE=email
SAML2_EXTERNAL_ID_ATTRIBUTE=uid
SAML2_IDP_ENTITYID=https://your-idp-entity-id
SAML2_IDP_SSO=https://your-idp.example.com/sso
SAML2_IDP_SLO=https://your-idp.example.com/slo
SAML2_IDP_x509=MIIC...paste-cert-contents-as-single-line...
SAML2_AUTOLOAD_METADATA=false

Upload your BookStack metadata (at /saml2/metadata) to your IdP and you're done.

OIDC (OpenID Connect)

Works with Google Workspace, Auth0, Keycloak, Authentik, GitLab, and most modern providers:

AUTH_METHOD=oidc
OIDC_NAME=Keycloak
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=bookstack
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER=https://sso.example.com/realms/company
OIDC_ISSUER_DISCOVER=true

After editing .env for any SSO method, clear the cache:

cd /var/www/bookstack
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan config:cache

Log out and you'll see the new SSO button on the login page.

Post-Install Hardening

A few small touches turn this into a production install you can leave unattended.

Schedule the BookStack cron. Some background jobs (notification batching, search index rebuilds) run via Laravel's scheduler. Add this to root's crontab with sudo crontab -e:

    * cd /var/www/bookstack && php artisan schedule:run >> /dev/null 2>&1

Enable automatic security updates:

sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades

Tighten the firewall:

sudo ufw allow OpenSSH
sudo ufw allow 'Apache Full'
sudo ufw enable

Set up nightly backups. A minimal backup script:

sudo tee /usr/local/bin/bookstack-backup.sh > /dev/null <<'EOF'
#!/bin/bash
DATE=$(date +%F)
BACKUP_DIR=/var/backups/bookstack
mkdir -p $BACKUP_DIR
mysqldump -u bookstack -p'STRONG_PASSWORD_HERE' bookstack | gzip > $BACKUP_DIR/db-$DATE.sql.gz
tar czf $BACKUP_DIR/uploads-$DATE.tar.gz -C /var/www/bookstack storage/uploads public/uploads
find $BACKUP_DIR -mtime +14 -delete
EOF
sudo chmod +x /usr/local/bin/bookstack-backup.sh

Schedule it at 03:00 daily:

0 3   * /usr/local/bin/bookstack-backup.sh

Push the resulting tarballs to S3, Backblaze B2, or another VPS for offsite safety.

FAQ

Is BookStack really free?

Yes. BookStack is released under the MIT license and is free for personal and commercial use with no seat limits and no feature gating. You only pay for the VPS it runs on. The project accepts donations and sells a paid plugin ecosystem, but the core product is unrestricted.

How much RAM does BookStack need?

BookStack runs comfortably on 2 GB of RAM for teams of up to 50 active editors, which is why the Starter VPS plan is recommended. Larger deployments with heavy attachment usage (PDFs, images, diagrams) benefit from 4 GB+ and an S3-compatible object storage backend for uploads to keep the application server lean.

Can I migrate from Confluence to BookStack?

Yes, with some effort. BookStack has a public REST API that can be scripted to bulk-create books, chapters, and pages. Community tools exist to convert Confluence HTML exports into BookStack-compatible HTML, and the default WYSIWYG editor accepts pasted-in content reasonably well. Expect manual cleanup for Confluence macros (expand panels, info boxes, Jira links) and attachments — but the basic content migration is very doable over a weekend for most wikis.

Does BookStack support SSO?

Yes, out of the box. BookStack supports LDAP / Active Directory, SAML 2.0, and OIDC (OpenID Connect), as well as prebuilt social login integrations for Google, GitHub, Azure AD, Okta, Discord, Slack, Twitch, and Keycloak. Everything is configured via .env values, with no extra plugins to install.

How do I back up BookStack?

Two things need backing up: the MariaDB database (all content, users, permissions, settings) and the uploads directories (storage/uploads and public/uploads, containing user-uploaded images and attachments). A nightly mysqldump plus a tar of the uploads — shipped offsite to S3 or Backblaze B2 — is the standard approach. See the backup script in the Post-Install Hardening section above.

Can I use PostgreSQL instead of MariaDB?

No. BookStack officially supports only MySQL 8.0+ and MariaDB 10.6+. PostgreSQL is not on the upstream project's roadmap. If you're committed to PostgreSQL, Wiki.js or Outline are better fits — both use PostgreSQL as their primary database.

How is BookStack different from Wiki.js, Outline, DokuWiki, and Trilium?

BookStack enforces a book/chapter/page structure that mirrors printed documentation — ideal for structured manuals, onboarding guides, and runbooks. Content is organized, but the structure is rigid.

Wiki.js is a Node.js wiki with a flexible tree-based page structure, more modern UI, and Markdown-first editing. Best when you want a flat namespace you can organize freely.

Outline is a modern, real-time collaborative wiki built for product teams, heavily influenced by Notion's UX. Best for teams who want Notion-like editing without the SaaS lock-in.

DokuWiki is the granddaddy of PHP wikis — file-based (no database), plugin-heavy, extremely lightweight. Best for small teams, homelabs, and deployments where simplicity beats polish.

Trilium is a personal knowledge base with a tree structure, note cloning, and scripting. Best for individuals and small research teams rather than company-wide wikis.

For most internal engineering or ops teams with 5-500 people, BookStack is the safest default.

Next Steps

Your BookStack instance is live, HTTPS-terminated, backed up, and SSO-ready. Here's what to do next:

• Seed the structure. Create two or three Shelves that map to major domains — Engineering, Product, Ops, People — and build a first Book in each. A visible skeleton encourages people to contribute.
• Import existing docs. Paste in your current Google Docs and Confluence pages now, while the initial enthusiasm is high. Stale docs are better than missing docs.
• Set up watched pages. Encourage team leads to "watch" critical books so they get email notifications on edits.
• Install the API-based backup tool. Consider running bookstack-file-exporter alongside the SQL backup for Markdown exports that survive even a total rebuild.
• Read the full docs. The official docs at bookstackapp.com/docs cover custom HTML/CSS, branding, the REST API, and advanced permissions.

Need a VPS to run BookStack on?

The Starter plan is sized perfectly for a 50-seat team wiki: 2 vCPU, 4 GB RAM, 50 GB NVMe SSD, snapshots included.

Launch your BookStack VPS now and own your team's knowledge.