Deployment guide

BookStack

Videos

Overview: BookStack on Ubuntu 24.04 LTS on Azure: overview (watch on YouTube)

Launch and log in: BookStack on Ubuntu 24.04 LTS on Azure: launch and log in (watch on YouTube)

Deep Dive: BookStack on Ubuntu 24.04 LTS on Azure: deep dive (watch on YouTube)

Overview

BookStack is a popular free, open-source platform for organizing and storing documentation and knowledge. Content is arranged into Shelves, Books, Chapters and Pages, with a powerful WYSIWYG and Markdown editor, full-text search, page revisions and history, built-in diagrams.net drawing, roles and granular permissions, and a full REST API.

The SecureAnyCloud image delivers BookStack fully installed and configured on Ubuntu 24.04. It is a Laravel application on PHP 8.3 with OPcache, served by nginx with php-fpm and backed by MariaDB. Database migrations are already applied, so you land directly on the sign-in page. There is no setup wizard to complete.

What you get:

BookStack 26.05 (MIT licensed), served from /var/www/bookstack/public
nginx, PHP 8.3 (php8.3-fpm with OPcache) and MariaDB, all from Ubuntu 24.04 main/universe
A dedicated Azure data disk at /var/lib/mysql (database tier) and a second at /var/www (application code, docroot and uploads). Each disk is independently resizable, separate from the OS disk, and re-provisioned with every VM.
A per-VM administrator email and password, MariaDB password and Laravel APP_KEY, all generated at first boot and written to a root-only file
nginx.service, php8.3-fpm.service and mariadb.service as systemd units, enabled and active
A health endpoint at /status that returns HTTP 200 when the database, cache and session are healthy
24/7 SecureAnyCloud support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.
Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point. Scale up for larger teams or heavier search workloads.
NSG inbound rules that allow 22/tcp from your management network and 80/tcp from your users. Add 443/tcp once you enable HTTPS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for BookStack by SecureAnyCloud, and select Create.
On Basics, pick your subscription, resource group, region and size.
Under Administrator account, choose SSH public key and paste your key.
Under Inbound port rules, allow SSH (22) and HTTP (80).
On the Disks tab, review the two dedicated data disks. Then select Review + create, followed by Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:bookstack-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name bookstack \
  --image sac1647283583153:bookstack-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name bookstack --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

The three services that back BookStack should all report active. The open health endpoint returns the database, cache and session state.

systemctl is-active nginx php8.3-fpm mariadb curl -s http://127.0.0.1/status

Expected output: three lines of active, then {"database":true,"cache":true,"session":true}.

Step 5 - Retrieve your administrator credentials

On the first boot of every VM, a one-shot service (bookstack-firstboot.service) generates credentials that are unique to that VM. These are a fresh Laravel application key, a fresh MariaDB password, and a fresh administrator email and password.

The service sets the VM's own address as the application URL automatically. No shared or default credentials ship in the image.

sudo cat /root/bookstack-credentials.txt

The file (mode 0600, root only) contains the administrator email (bookstack.admin.user), the administrator password (bookstack.admin.pass), the BookStack URL and the database credentials. BookStack signs in by email.

Step 6 - Sign in

Browse to http://<vm-public-ip>/ and sign in with the administrator email and password from the credentials file. You land on the BookStack home page, ready to create your first shelf, book and pages.

You can also prove the login round trip from the VM's own shell. The command reads the per-VM credentials, fetches a CSRF token and posts a real sign-in. A successful BookStack login answers HTTP 302.

ADMIN_USER=$(sudo grep '^bookstack.admin.user=' /root/bookstack-credentials.txt | cut -d= -f2-)
ADMIN_PASS=$(sudo grep '^bookstack.admin.pass=' /root/bookstack-credentials.txt | cut -d= -f2-)
CJ=$(mktemp)
TOK=$(curl -s -c "$CJ" http://127.0.0.1/login | grep -oE 'name="_token" value="[^"]+"' | head -1 | sed 's/.*value="//;s/"//')
curl -s -o /dev/null -w 'login HTTP %{http_code}\n' -b "$CJ" -c "$CJ" \
  -d "_token=$TOK" --data-urlencode "email=$ADMIN_USER" --data-urlencode "password=$ADMIN_PASS" \
  http://127.0.0.1/login rm -f "$CJ"

Step 7 - Organize your knowledge base

BookStack's hierarchy is Shelves > Books > Chapters > Pages. From the header, choose Shelves to group related books. Choose Create New Book to start a manual or runbook collection, then add chapters and pages inside it.

Every page supports the WYSIWYG editor or Markdown, drawings via diagrams.net, attachments, and full revision history. Use Settings > Roles for granular permissions and Settings > Users to invite your team.

Step 8 - Confirm the version and the data tiers

cat /var/www/bookstack/version df -h /var/lib/mysql /var/www

The database tier (/var/lib/mysql) and the application tier (/var/www, which holds code, docroot and user uploads) each live on their own dedicated Azure data disk. You can grow storage for either tier without disturbing the OS disk.

Administration from the CLI

Run admin CLI tasks with Laravel's artisan as the www-data user. For example, list the available BookStack commands:

sudo -u www-data php /var/www/bookstack/artisan list

Common operations include bookstack:regenerate-search (rebuild the search index), bookstack:cleanup-images and bookstack:update-url (use it if you later move to a domain name).

Enabling HTTPS

For production, point a real domain at the VM's public IP and open 443/tcp in the NSG. Then terminate TLS at nginx with Let's Encrypt, replacing the domain with your own.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

After the certificate is issued, set the new address as the application URL.

sudo -u www-data php /var/www/bookstack/artisan bookstack:update-url http://<vm-public-ip> https://your-domain.example.com

Backup and maintenance

The database lives on the data disk at /var/lib/mysql. The application tree and uploads live on the data disk at /var/www.

Snapshot both disks in Azure for a point-in-time backup, or dump the database as shown below. The database password is in the credentials file.

sudo mariadb-dump bookstack > bookstack-backup.sql

Keep the OS patched with sudo apt update && sudo apt upgrade. Unattended security upgrades are enabled by default.

The stack restarts cleanly with sudo systemctl restart nginx php8.3-fpm mariadb.

Support

This image is backed by 24/7 SecureAnyCloud support. Contact us by email or chat for help with BookStack deployment, upgrades, LDAP and SAML single sign-on, email and storage configuration, REST API integration, performance tuning and database administration.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on Azure

Launch BookStack on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

BookStack is a free, open-source platform for organizing and storing documentation and knowledge. Content is arranged into Shelves, Books, Chapters and Pages, with a powerful WYSIWYG and Markdown editor, full-text search, page revisions and history, built-in diagrams.net drawing, roles and granular permissions, and a full REST API.

This SecureAnyCloud Amazon Machine Image delivers BookStack fully installed and configured on Ubuntu 24.04, so a complete knowledge base is running within minutes of launch. The stack is a Laravel application on PHP 8.3 with OPcache, served by nginx with php-fpm, backed by MariaDB. Database migrations are already applied, so you land directly on the sign-in page. There is no setup wizard to complete.

This guide covers connecting to your instance, retrieving the per-instance administrator credentials, signing in, creating your first content, and enabling HTTPS.

Architecture at a glance

Application: BookStack 26.05 (Laravel), served from /var/www/bookstack/public
Web server: nginx, listening on port 80
PHP: PHP 8.3 (php8.3-fpm) with OPcache
Database: MariaDB 10.11, datadir on a dedicated EBS volume at /var/lib/mysql
Application storage: code and uploads on a dedicated EBS volume at /var/www
Health endpoint: http://<instance-public-ip>/status (returns HTTP 200 when healthy)

The database tier and the application tier each live on their own independently resizable EBS volume, separate from the operating-system disk. You can grow storage for either tier without disturbing the other.

Connecting to your instance

Connect over SSH on port 22 as the default login user for your operating-system variant.

For Ubuntu 24.04, the SSH login user is ubuntu.

ssh -i /path/to/your-key.pem ubuntu@<instance-public-ip>

Replace <instance-public-ip> with the public IPv4 address of your instance (visible in the EC2 console), and /path/to/your-key.pem with the private key you launched the instance with.

Per-instance credentials

On the first boot of every instance, a one-shot service (bookstack-firstboot.service) generates credentials that are unique to that instance:

A fresh Laravel application key (APP_KEY).
A fresh MariaDB database password.
A fresh administrator email and password.

The service sets the instance's own address as the application URL automatically. No shared or default credentials ship in the image.

Retrieve the generated administrator login with this command.

sudo cat /root/bookstack-credentials.txt

The file (mode 0600, root only) contains the administrator email, the administrator password, the BookStack URL and the database credentials. BookStack signs in by email.

Verifying the service

The three services that back BookStack should all report active.

systemctl is-active nginx php8.3-fpm mariadb

Expected output:

active active active

Confirm the installed BookStack version.

cat /var/www/bookstack/version

v26.05.1

BookStack exposes an open health endpoint at /status. It checks the database, cache and session subsystems and returns HTTP 200 when all are healthy.

curl -s http://localhost/status

{"database":true,"cache":true,"session":true}

Confirm that the database and application tiers are on their dedicated EBS volumes.

df -h /var/www /var/lib/mysql

Filesystem Size Used Avail Use% Mounted on /dev/nvme1n1 30G 156M 28G 1% /var/www /dev/nvme2n1 20G 194M 19G 2% /var/lib/mysql

Signing in

Browse to your instance and sign in with the administrator email and password from /root/bookstack-credentials.txt.

http://<instance-public-ip>/

After signing in you land on the BookStack home page, which surfaces recently updated pages and recent activity across your knowledge base.

Change the administrator email and password, and create additional named user accounts, from Settings > Users once you are signed in. We strongly recommend both.

Organising your content

BookStack organizes knowledge in a simple, predictable hierarchy:

Shelves group related Books. Think of a shelf as a category or a team.
Books contain Chapters and Pages.
Chapters group related Pages within a book.
Pages hold your actual content, written in the WYSIWYG or Markdown editor.

The Shelves view lists every shelf in your knowledge base. Open a shelf to see the books it contains.

Open a book to see its chapters and pages, and to add new content with New Page and New Chapter.

Each page renders rich content, including headings, tables, checklists, code blocks, callouts and diagrams. It also offers a breadcrumb trail back up through its chapter and book, page revisions, and in-page navigation.

To create your first content, click Shelves > New Shelf, then add a Book. Inside the book, create Chapters and Pages.

Use the search box at the top of every screen to find content instantly across the whole knowledge base.

Administering from the command line

BookStack ships Laravel's artisan CLI. Run admin tasks as the www-data user from the application root.

sudo -u www-data php /var/www/bookstack/artisan <command>

Common tasks:

... artisan bookstack:create-admin --email=you@example.com --name="Your Name" creates a new administrator account.
... artisan bookstack:reset-mfa --id=1 resets a user's multi-factor authentication.
... artisan cache:clear clears the application cache.

Manage the services with systemctl (nginx, php8.3-fpm, mariadb).

Enabling HTTPS

The image serves BookStack over HTTP on port 80, so it works immediately behind whatever networking you place in front of it. For production, terminate TLS either at an AWS Application Load Balancer or CloudFront in front of the instance, or directly on the instance with Let's Encrypt.

To use Let's Encrypt directly on the instance, point a DNS name at the instance's public IP, then install Certbot and request a certificate. Run the following commands, replacing the example domain and email with your own.

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com -m you@example.com --agree-tos --no-eff-email

Certbot obtains a certificate and reconfigures nginx for HTTPS. After enabling HTTPS, update BookStack's APP_URL to the https:// address in /var/www/bookstack/.env, then run sudo -u www-data php /var/www/bookstack/artisan config:cache so generated links use the new URL.

Support

This is a repackaged open-source software product. BookStack itself is licensed under the MIT License.

SecureAnyCloud provides 24/7 technical support for this image by email and chat. Support covers BookStack deployment, upgrades, performance tuning, LDAP and SAML single sign-on, email and storage configuration, REST API integration, and database administration.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch BookStack with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS