Overview Link to heading

Bookstack is a self-hosted, easy-to-use platform for organising and storing information. It’s the most aesthetic option for documentation I have encountered and I use it regularly in my professional and personal life.

This guide will run you through getting it setup securely on AWS and will remain within the limits of the AWS Free Tier.

Server Setup Link to heading

First, create an AWS Account. Then go to Services > EC2 and Launch an Instance.

Select the free tier eligible Ubuntu Server 18.04 > t2.micro > default Instance Details > default Storage…

For Security, open ports 22, 80, and 443 for ssh, http and https respectively.

Then launch the instance.

Elastic IP Link to heading

I would recommend creating an Elastic IP for your instance. This allows it to retain it’s IP after shutting down.

Go to Services > VPN > Elastic IPs > Allocate Elastic IP Address > Allocate

Then select the new EIP and associate it with the new bookstack server.

Domain and DNS Link to heading

If you want to be able to access the server from a domain name instead of an IP address, you must first purchase a domain. You can do this on AWS if you go to Services > Route 53 > Domain > Register Domain.

Once you have a domain registered, created a DNS record for that domain in Route 53 and point it to the Elastic IP of the bookstack server.

Services > Route 53 > Hosted Zone > Select new domain > Create Record Set > Type: A - IPv4 address > Value: IP address of bookstack server > Create

Bookstack Setup Link to heading

Once the server and networking is setup, connect to the instance with ssh following the instruction on AWS EC2 when selecting the instance and clicking “Connect”.

Bookstack makes it really easy to install and provides a script to do it for you.

Once ssh’ed into the server, follow the installation instructions for your OS. If you’re following this guide and are using Ubuntu 18.04:

# Download the script
wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-18.04.sh

# Make it executable
chmod a+x installation-ubuntu-18.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-18.04.sh

HTTPS with Lets Encrypt and Certbot Link to heading

To enable secure browsing with https we will use Lets Encrypt and Certbot: a free, automated and open Certificate Authority.

Certbot provides easy guides for your specific distribution here. I will cover my setup with Apache and Ubuntu 18.04.

Install certbot:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install certbot python-certbot-apache

Run certbot in certonly mode and follow the instructions:

sudo certbot certonly --apache

It should find your apache site (/etc/apache2/sites-available/bookstack.conf) and create a cert for it in /etc/letsencrypt/live/.

Edit the default apache config (/etc/apache2/sites-available/). We need to add a redirect from port :80 to :443, change the original vhost from :80 to :440, and add the SSL Cert file locations.

sudo chmod 600 /etc/apache2/sites-available/bookstack.conf
sudo vim /etc/apache2/sites-available/bookstack.conf

It should look something like this:

<VirtualHost *:80>
    ServerName <url>
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>
<VirtualHost *:443>
        ServerName <url>

        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/bookstack/public/

    SSLEngine on
    SSLCertificateFile          /etc/letsencrypt/live/<url>/fullchain.pem
    SSLCertificateKeyFile       /etc/letsencrypt/live/<url>/privkey.pem

    <Directory /var/www/bookstack/public/>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
        <IfModule mod_rewrite.c>
            <IfModule mod_negotiation.c>
                Options -MultiViews -Indexes
            </IfModule>

            RewriteEngine On

            # Handle Authorization Header
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

            # Redirect Trailing Slashes If Not A Folder...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_URI} (.+)/$
            RewriteRule ^ %1 [L,R=301]

            # Handle Front Controller...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>

        ErrorLog /error.log
        CustomLog /access.log combined

RewriteCond %{SERVER_NAME} =<url>
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

We then need to edit this bookstack configuration file (/var/www/bookstack/.env) and uncomment the APP_URL line and enter the url with https.

Enable apache SSL module:

sudo a2enmod ssl

Finally, test and reload the apache config

sudo apache2ctl configtest
sudo service apache2 reload

Check with a browser to make sure the page is secure. If the site is still insecure but the certs are showing up as valid. Check the console with F12 and reload the page to see what’s causing the issue. I had an issue with the custom Application Logo since it was uploaded when the page was still insecure. I had to go to settings, reset and save, then reupload the image.