BookStack on AWS User Guide

BookStack is a free, open source platform for organising 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 cloudimg 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

The database tier and the application tier each live on their own independently-resizable EBS volume, separate from the operating-system disk, so 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.

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, and
• a fresh administrator email and password.

The instance's own address is set as the application URL automatically. No shared or default credentials ship in the image. Retrieve the generated administrator login with:

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 that 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 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.

We strongly recommend changing the administrator email and password, and creating additional named user accounts, from Settings → Users once you are signed in.

Organising your content

BookStack organises 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 — headings, tables, checklists, code blocks, callouts and diagrams — with 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, and inside it 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" — create a new administrator account.
• ... artisan bookstack:reset-mfa --id=1 — reset a user's multi-factor authentication.
• ... artisan cache:clear — clear 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 use, terminate TLS — either at an AWS Application Load Balancer / 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, replacing the placeholders with your own domain and email:

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 will obtain a certificate and reconfigure 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. cloudimg provides 24/7 technical support for this image by email and chat — covering 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.