Skip to main content

Manual Install

The OS is Ubuntu 22.04, web server is Nginx, database is Mariadb.

Initial Networking Configuration

If you are installing this on a VPS, you should skip this step or if you really want SystemD networking, Look up what the config file should be for a static IP.

Netplan will be removed as the network manager as it is needlessly complex, especially for the purpose and configuration of this server.

sudo apt install network-manager
sudo apt purge netplan.io

You can use nano (good for beginners) or vim to create the networking config file.

sudo vim /etc/systemd/network/05-eth0.network

Config:

[Match]
Name=eth0

[Network]
DHCP=yes

Reboot to apply networking changes.

sudo reboot

Required Packages

These are the packages required for the installation of Hesk.

sudo apt install ufw nginx mariadb-server
sudo apt install php8.1 php8.1-common php8.1-cli php8.1-gd php8.1-mysql php8.1-xml php8.1-ldap php8.1-fpm php8.1-imap php8.1-curl

Firewall

Uncomplicated FireWall (UFW) will be the firewall on this server, we need to configure it to allow ssh, http, https, and imap traffic. We can later configure the ssh port to be something non-standard so that our server is more secure.

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw disable
sudo ufw enable

MySQL

Run this to enter the MySQL prompt.

sudo mysql -uroot -p

Then a mysql> or MariaDB [root]> prompt will appear. Now enter the following lines and confirm them with the enter key. The username can be whatever you like, but be sure to replace password with a good password. These will be used later when initially configuring Bookstack from the browser.

CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';
CREATE DATABASE IF NOT EXISTS bookstackdb;
GRANT ALL PRIVILEGES ON heskdb.* TO 'bookstack'@'localhost' IDENTIFIED BY 'password';

Installing Bookstack

Source

  1. Clone the release branch of the BookStack GitHub repository into a folder.

    git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch

  2. cd into the application folder and run composer install --no-dev.
  3. Copy the .env.example file to .env and fill with your own database and mail details.
  4. Ensure the storage, bootstrap/cache & public/uploads folders are writable by the web server (More information here).
  5. In the application root, Run php artisan key:generate to generate a unique application key.
  6. If not using Apache or if .htaccess files are disabled you will have to create some URL rewrite rules as shown below.
  7. Set the web root on your server to point to the BookStack public folder. This is done with the root setting on Nginx or the DocumentRoot setting on Apache.
  8. Run php artisan migrate to update the database.
  9. Done! You can now login using the default admin details admin@admin.com with a password of password. You should change these details immediately after logging in for the first time.


Set the correct owner and permissions on some files

sudo chown www-data:www-data -R /var/www/bookstack

Nginx

The web server is the core to any web app, this one uses nginx.

Nginx Configuration

Create the nginx config file.

sudo vim /etc/nginx/conf.d/web.site.net.conf
server {
        listen 80;
        server_name web.site.net;
        add_header Strict-Transport-Security max-age=2592000;
        rewrite ^ https://web.site.net$request_uri? permanent;
}

server {
        listen 443 ssl;
        ssl_certificate /etc/certs/cert.crt;
        ssl_certificate_key /etc/certs/cert.key;
        ssl_session_timeout 5m;
        ssl_ciphers 'AES256+EECDH:AES256+EDH:!aNULL';
        ssl_protocols TLSv1.3;
        ssl_prefer_server_ciphers on;
        add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' data:;";
        add_header X-XSS-Protection "1; mode=block";


        access_log /var/log/nginx/bookstack.access.log;
        error_log /var/log/nginx/bookstack.error.log;
        server_name web.site.net;

        root /var/www/hesk;

        index index.php;

        client_max_body_size 20M;
  
        location / {
                # First attempt to serve request as file, then
                # as directory, then fall back to displaying a 404.
                try_files $uri $uri/ =404;
        }

        location ~ \.php$ {
                fastcgi_split_path_info ^(.+\.php)(/.+)$;
                fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
                fastcgi_index index.php;
                include fastcgi_params;
                fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
                fastcgi_intercept_errors off;
                fastcgi_buffer_size 16k;
                fastcgi_buffers 4 16k;
        }
        #location "~^/admin/.*" {
        #        try_files $uri $uri/ =404;
        #        auth_basic "Restricted";
        #        auth_basic_user_file /etc/nginx/.htpasswd;
        #}

        #location ~ /admin/ {
        #        try_files $uri $uri/ =404;
        #        auth_basic "Restricted";
        #        auth_basic_user_file /etc/nginx/.htpasswd;
        #}

        location ~ /\.ht {
                deny all;
        }
}

SSL Certification

Cert keys were transferred to the server and stored in ''/etc/certs''. This directory had to be created and the permissions set on the directory so that the files are safe. It should also be verified that the folder and files are owned by root.

sudo mkdir /etc/certs

After transfer the permissions need to be set like so

sudo chmod 400 -R /etc/certs
sudo rm -rf /etc/nginx/sites-enabled/default

Check the config for errors first

sudo nginx -t

Restart the nginx service

sudo systemctl restart nginx
Back to top