Christian WellsBookStack is a versatile and user-friendly platform for organizing and storing information. It can be used as a wiki, documentation website, or note-taking application. Built on the Laravel PHP framework and utilizing MySQL for data storage, BookStack offers features such as a WYSIWYG or Markdown editor, multi-factor authentication, dark mode, and multilingual support. In this tutorial, we will guide you through the process of installing BookStack on a Ubuntu 20.04 server, using Nginx as the web server.
Prerequisites
Before we begin, make sure you have the following:
- A server running Ubuntu 20.04
- A Fully Qualified Domain Name (FQDN) pointing to the server
- A non-root user with sudo privileges
- PHP version 7.3 or greater
- MySQL version 5.6 or greater, or MariaDB version 10.0 or greater
- Git and Composer installed
Now that we have everything we need, let’s get started with the installation process.
Step 1: Configure Firewall
First, we need to configure the firewall to allow incoming connections. Ubuntu comes with a firewall called UFW (Uncomplicated Firewall) by default. Check if the firewall is running by executing the following command:
sudo ufw status
If the firewall is inactive, enable it by running:
sudo ufw enable
Next, allow SSH, HTTP, and HTTPS traffic through the firewall:
sudo ufw allow OpenSSH sudo ufw allow 80 sudo ufw allow 443
Verify the firewall rules by running:
sudo ufw status
Step 2: Install Git
Git is a version control system that is used to download and update BookStack. Install Git by running the following command:
sudo apt install git
Verify the installation by checking the Git version:
git --version
Step 3: Install PHP and Extensions
BookStack relies on PHP, so we need to install PHP and its extensions. By default, Ubuntu ships with an outdated version of PHP. We will use Ondrej’s PHP repository to install PHP 7.4, which is the recommended version for BookStack. Add the repository by running:
sudo add-apt-repository ppa:ondrej/php
Next, install PHP and the required extensions:
sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql
Verify the installation by checking the PHP version:
php --version
Step 4: Install and Configure MariaDB
BookStack requires a database to store its data. We will use MariaDB, which is a drop-in replacement for MySQL. By default, Ubuntu ships with an older version of MariaDB, so we need to add the official MariaDB repository to install the latest version. Run the following commands to add the repository and install MariaDB:
curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup sudo bash mariadb_repo_setup --mariadb-server-version=10.6 sudo apt install mariadb-server
After the installation, secure the MariaDB installation by running:
sudo mysql_secure_installation
Follow the prompts to set the root password, remove anonymous users, disallow remote root login, remove the test database, and reload the privilege tables.
Next, create a new database and user for BookStack:
sudo mysql
In the MySQL shell, run the following commands to create the database and user:
CREATE DATABASE bookstack; CREATE USER 'bookstackuser'@'localhost' IDENTIFIED BY 'bookstackpassword'; GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstackuser'@'localhost'; FLUSH PRIVILEGES; EXIT;
Replace ‘bookstackuser’ and ‘bookstackpassword’ with your desired username and password.
Step 5: Install Composer
Composer is a dependency management tool for PHP, and it is required by Laravel, the framework on which BookStack is built. Download the Composer installer script by running:
curl -sS https://getcomposer.org/installer -o composer-setup.php
Verify the installer by running the following commands:
HASH=`curl -sS https://composer.github.io/installer.sig`
echo $HASH
php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
If the installer is verified, proceed with the installation:
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
Verify the installation by checking the Composer version:
composer --version
Step 6: Download and Install BookStack
Create a directory for the BookStack installation:
sudo mkdir -p /var/www/bookstack
Change the ownership of the directory to the current user:
sudo chown -R $USER:$USER /var/www/bookstack
Clone the BookStack repository into the directory:
cd /var/www/bookstack git clone https://github.com/BookStackApp/BookStack.git --branch=release --single-branch.
Install the required dependencies using Composer:
composer install --no-dev
Copy the example environment file and edit it:
cp.env.example.env sudo nano.env
Update the following lines in the .env file to match your configuration:
APP_URL=https://example.com DB_HOST=localhost DB_DATABASE=bookstack DB_USERNAME=bookstackuser DB_PASSWORD=bookstackpassword
Save the file and exit the editor.
Generate a unique application key:
php artisan key:generate
Update the database schema:
php artisan migrate
Clear the cache:
php artisan cache:clear php artisan config:clear php artisan view:clear
Step 7: Install Let’s Encrypt SSL
To secure your BookStack installation with an SSL certificate, we will use Let’s Encrypt and their Certbot tool. Install Snap, the package installer for Snapd:
sudo apt install snapd
Ensure that Snapd is up to date:
sudo snap install core sudo snap refresh core
Install Certbot:
sudo snap install --classic certbot
Create a symbolic link to the Certbot command:
sudo ln -s /snap/bin/certbot /usr/bin/certbot
Generate the SSL certificate:
sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m test@example.com -d example.com
This command will download the SSL certificate to the /etc/letsencrypt/live/example.com directory on your server.
Generate a Diffie-Hellman group certificate:
sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048
Create a challenge web root directory for Let’s Encrypt auto-renewal:
sudo mkdir -p /var/lib/letsencrypt
Create a cron job to renew the SSL certificate automatically. Open the renew script:
sudo nano /etc/cron.daily/certbot-renew
Add the following code to the file:
#!/bin/sh certbot renew --cert-name example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
Save the file and exit the editor. Make the script executable:
sudo chmod +x /etc/cron.daily/certbot-renew
Step 8: Install and Configure Nginx
Ubuntu ships with an older version of Nginx, so we will install the latest version from the official Nginx repository. Add the repository:
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list
Install Nginx:
sudo apt update sudo apt install nginx
Enable the Nginx service:
sudo systemctl enable nginx
Step 9: Configure PHP-FPM
To ensure that PHP-FPM works correctly with Nginx, we need to make a few configuration changes. Open the PHP-FPM configuration file:
sudo nano /etc/php/7.4/fpm/pool.d/www.conf
Change the following lines to set the user and group to nginx:
user = nginx group = nginx
Save the file and exit the editor.
Find the following lines in the Nginx configuration file:
listen.owner = www-data listen.group = www-data
Change them to:
listen.owner = nginx listen.group = nginx
Save the file and exit the editor.
Restart the PHP-FPM service:
sudo systemctl restart php7.4-fpm
Step 10: Configure Nginx
Create a new Nginx configuration file for BookStack:
sudo nano /etc/nginx/conf.d/bookstack.conf
Add the following code to the file:
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name bookstack.example.com;
access_log /var/log/nginx/bookstack.access.log;
error_log /var/log/nginx/bookstack.error.log;
ssl_certificate /etc/letsencrypt/live/bookstack.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/bookstack.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem;
ssl_session_timeout 5m;
ssl_session_cache shared:MozSSL:10m;
ssl_session_tickets off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
ssl_stapling on;
ssl_stapling_verify on;
ssl_dhparam /etc/ssl/certs/dhparam.pem;
root /var/www/bookstack/public;
index index.php index.html;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_pass unix:/run/php/php7.4-fpm.sock;
}
}
# enforce HTTPS
server {
listen 80;
listen [::]:80;
server_name bookstack.example.com;
return 301 https://$host$request_uri;
}
Replace example.com with your domain name.
Save the file and exit the editor.
Open the main Nginx configuration file:
sudo nano /etc/nginx/nginx.conf
Add the following line before the include /etc/nginx/conf.d/*.conf; line:
server_names_hash_bucket_size 64;
Save the file and exit the editor.
Verify the Nginx configuration:
sudo nginx -t
If there are no syntax errors, start the Nginx service:
sudo systemctl start nginx
Step 11: Run BookStack
Your BookStack installation is now ready to use. Open your web browser and visit https://example.com (replace example.com with your domain name). You should see the BookStack login page.
Log in using the default administrator account:
- Email: test@example.com
- Password: password
Once logged in, go to Settings > Users and click on the “Add New User” button. Fill in the user details, checkmark the “Admin” box under User Roles, and uncheck the “Send user invite email” option. Select a strong password and click “Save” when finished.
Next, click on the default “Admin” user and delete it by clicking the “Delete User” button. Transfer the ownership of the Admin user to the newly created user by selecting it from the dropdown menu before deleting it. Click “Confirm” to finish. You will be automatically logged out and will need to log back in with the newly created user.
Step 12: Backup and Restore BookStack
It is important to regularly backup your BookStack installation to protect your data. To back up the database, use the mysqldump tool:
sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql
To back up the files, create a compressed archive of the following files and folders:
.env– file containing important configurationpublic/uploads– folder containing uploaded imagesstorage/uploads– folder containing uploaded page attachments
sudo tar -czvf bookstack-files-backup.tar.gz.envpublic/uploads storage/uploads
To restore the BookStack installation from a backup, follow these steps:
- Restore the database:
sudo mysql -u bookstackuser bookstack < bookstack.backup.sql
Note: If you are restoring to a new version of BookStack, you may need to run the php artisan migrate command to update the database schema.
- Restore the compressed files:
sudo tar -xvzf bookstack-files-backup.tar.gz
- Update file permissions:
sudo chown -R nginx:nginx /var/www/bookstack
Conclusion
Congratulations! You have successfully installed BookStack with Nginx on your Ubuntu 20.04 server. You can now start organizing and storing information using this powerful platform. By following the steps outlined in this tutorial, you have created a secure and efficient BookStack installation. If you have any questions or need assistance, feel free to reach out to our team at Shape.host. We provide reliable Linux SSD VPS hosting services to empower businesses with scalable and secure cloud hosting solutions. Visit us at Shape.host for more information.
