How to Install BookStack on NixOS

BookStack is a free and open-source wiki platform that allows users to create and organize content in a user-friendly way. It is built using PHP and Laravel framework which makes it highly customizable and easy to use.

In this tutorial, we will cover the steps required to install BookStack on the latest version of NixOS. Follow the steps below to get started:

Step 1 - Updating Nix Packages

Before installing BookStack, we need to ensure that all Nix packages are up to date. This can be done by running the following commands:

$ sudo nix-channel --update
$ sudo nix-env -iA nixpkgs.nix

Step 2 - Installing Required Packages

We need to install Apache web server, PHP, and MySQL packages as these are the prerequisites needed to run BookStack. To install these packages, run the following commands:

$ sudo nix-env -iA nixpkgs.apacheHttpd
$ sudo nix-env -iA nixpkgs.php74
$ sudo nix-env -iA nixpkgs.mariadb

Step 3 - Installing BookStack

To install BookStack, follow the steps below:

1. Create a new directory to hold the BookStack files:

$ sudo mkdir /var/www/bookstack

2. Change the ownership and permissions of the directory as follows:

$ sudo chown www-data:www-data /var/www/bookstack
$ sudo chmod 775 /var/www/bookstack

3. Download the latest release of BookStack:

$ sudo curl -s https://api.github.com/repos/BookStackApp/BookStack/releases/latest \
| grep "browser_download_url.*zip" \
| cut -d : -f 2,3 \
| tr -d \" \
| wget -O bookstack.zip -qi -

4. Unzip the downloaded file:

$ sudo unzip bookstack.zip -d /var/www/bookstack

5. Rename the extracted directory:

$ sudo mv /var/www/bookstack/BookStack-* /var/www/bookstack/bookstack

6. Change the ownership of the BookStack directory:

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

Step 4 - Configuring Apache

BookStack needs to be configured with an Apache virtual host. To create the virtual host, follow the steps below:

1. Create a new file called bookstack.conf in the /etc/apache2/vhosts.d/ directory:

$ sudo nano /etc/apache2/vhosts.d/bookstack.conf

2. Paste the following Apache virtual host configuration:

<VirtualHost *:80>

    ServerName bookstack.example.com
    ServerAlias www.bookstack.example.com
    DocumentRoot /var/www/bookstack/bookstack/public

    <Directory /var/www/bookstack/bookstack/public>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog /var/log/apache2/bookstack_error.log
    CustomLog /var/log/apache2/bookstack_access.log combined

</VirtualHost>

Note: Replace bookstack.example.com and www.bookstack.example.com with your domain name.

3. Save and close the file.

Step 5 - Configuring MySQL

We need to create a database and user for BookStack. To create a new database and user, run the following commands:

$ sudo mysql -u root

1. Create a new database:

mysql> CREATE DATABASE bookstack;

2. Create a new user:

mysql> CREATE USER 'bookstack_user'@'localhost' IDENTIFIED BY 'password';

Note: Replace password with your desired password.

3. Grant privileges to the user for the database:

mysql> GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack_user'@'localhost';

4. Flush privileges and exit:

mysql> FLUSH PRIVILEGES;
mysql> EXIT;

Step 6 - Configuring BookStack

We need to configure the BookStack environment file. To do this, run the following commands:

1. Copy the example environment file:

$ sudo cp /var/www/bookstack/bookstack/.env.example /var/www/bookstack/bookstack/.env

2. Open the .env file and edit the following line:

APP_URL="http://bookstack.example.com"

Note: Replace bookstack.example.com with your domain name.

3. Edit the following lines to match your MySQL database configuration:

DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack_user
DB_PASSWORD=password

Note: Replace password with your MySQL password.

Step 7 - Running Migrations

We need to run the BookStack migrations to create the necessary database tables. To do this, run the following command:

$ php /var/www/bookstack/bookstack/artisan migrate

Step 8 - Configuring SELinux

If you are running SELinux, you may need to grant Apache permissions to access the BookStack files. To do this, run the following command:

$ sudo chcon -R -t httpd_sys_rw_content_t /var/www/bookstack

Step 9 - Starting Apache

To start Apache, run the following command:

$ sudo systemctl start apache2

Step 10 - Accessing BookStack

BookStack is now installed and configured. Open your web browser and navigate to your BookStack domain name to start using BookStack.

Congratulations! You have successfully installed BookStack on NixOS.