Innovate | Connect | Transform
ContactService statusUSD $

GICT knowledge base

How to Setup BookStack Wiki on Ubuntu 24.04 Server

Published

Deployments

BookStack is a free wiki software that helps you create and organize documentation. It works like a digital library where you can create books, chapters, and pages. You can use it for team documentation, user manuals, or knowledge bases.

This guide will show you how to install BookStack on Ubuntu 24.04. When you’re done, you’ll have your own wiki website that you control completely.

What You Need

Before starting, make sure you have:

  • Ubuntu 24.04 server with sudo access
  • At least 1GB RAM (2GB is better)
  • 10GB free disk space
  • Internet connection

Update Your System

First, update your server to get the latest packages. This ensures you have the most recent security patches and software versions:

sudo apt update && sudo apt upgrade -y

The update command refreshes the package list, while upgrade installs any available updates.

Install Required Software

BookStack needs several programs to work properly. We’ll install Apache (web server), MySQL (database), PHP (programming language), and some additional tools:

# Install web server
sudo apt install apache2 -y

# Install database
sudo apt install mysql-server -y

# Install PHP and extensions
sudo apt install php php-mysql php-gd php-mbstring php-tokenizer php-xml php-zip php-curl php-ldap php-tidy php-fileinfo -y

# Install other tools
sudo apt install git curl unzip -y

Each component serves a specific purpose:

  • Apache serves your wiki to web browsers
  • MySQL stores all your wiki content and user data
  • PHP runs the BookStack application
  • Git downloads BookStack from the internet

Install Composer

Composer is a tool that manages PHP packages. BookStack uses many external libraries, and Composer automatically downloads and installs them:

# Download Composer
curl -sS https://getcomposer.org/installer -o composer-setup.php

# Install it
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# Clean up
rm composer-setup.php

# Check if it works
composer --version

If the version command shows a version number, Composer is installed correctly.

Set Up Database

MySQL stores all your wiki data. First, we need to secure the installation by removing default accounts and settings:

sudo mysql_secure_installation

This script will ask several questions. Here’s what to choose:

  • Set a root password: Choose a strong password
  • Remove anonymous users: Yes (improves security)
  • Disable remote root login: Yes (prevents remote attacks)
  • Remove test database: Yes (not needed)
  • Reload privileges: Yes (applies changes)

Now create a database specifically for BookStack:

# Login to MySQL
sudo mysql -u root -p

# Create database and user (change 'your_password' to something secure)
CREATE DATABASE bookstack;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;
EXIT;

This creates:

  • A database called “bookstack” to store your wiki data
  • A user account that can only access this database
  • Proper permissions for security

Important: Write down the password you choose – you’ll need it later.

Download BookStack

Now we’ll download BookStack from its official source on GitHub:

# Go to web directory
cd /var/www

# Download BookStack
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack

# Set correct ownership
sudo chown -R www-data:www-data /var/www/bookstack

The --branch release flag ensures you get the stable version, not development code. The chown command gives Apache permission to read the files.

Install BookStack Dependencies

BookStack uses many PHP libraries. Composer will download and install all of them automatically:

cd /var/www/bookstack
sudo -u www-data composer install --no-dev --no-plugins

This process may take a few minutes as it downloads all necessary components. The --no-dev flag skips development tools we don’t need.

Configure BookStack

BookStack needs to know how to connect to your database and other important settings. We’ll create a configuration file:

# Copy the example config
sudo -u www-data cp .env.example .env

# Edit the config file
sudo nano .env

Find and update these important settings in the file:

# Your website URL (change to your domain or IP)
APP_URL=http://your-domain.com

# Database settings (use the password you created earlier)
DB_HOST=127.0.0.1
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=your_password

The APP_URL tells BookStack what web address to use for links and emails. Make sure this matches how people will access your wiki.

Set Up the Application

Now we’ll generate a security key and create the database structure:

# Generate encryption key
sudo -u www-data php artisan key:generate --no-interaction --force

# Create database tables
sudo -u www-data php artisan migrate --no-interaction --force

The encryption key secures your data, and the migration creates all the tables BookStack needs to store books, pages, users, and settings.

Configure Apache

Apache needs to know how to serve your BookStack website. We’ll create a virtual host configuration that tells Apache where to find BookStack and how to handle requests.

For more detailed information about Apache Virtual Hosts, you can read our comprehensive guide: Apache Virtual Hosts on Ubuntu

sudo nano /etc/apache2/sites-available/bookstack.conf

Add this content (change your-domain.com to your actual domain or server IP):

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/bookstack/public/

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

    ErrorLog ${APACHE_LOG_DIR}/bookstack_error.log
    CustomLog ${APACHE_LOG_DIR}/bookstack_access.log combined
</VirtualHost>

Key points about this configuration:

  • DocumentRoot points to BookStack’s public folder, not the main folder
  • AllowOverride All lets BookStack control URL formatting
  • Separate log files help with troubleshooting

Enable the website and required Apache modules:

# Enable URL rewriting (needed for clean URLs)
sudo a2enmod rewrite

# Enable BookStack site
sudo a2ensite bookstack.conf

# Disable default site (optional but recommended)
sudo a2dissite 000-default.conf

# Restart Apache to apply changes
sudo systemctl restart apache2

Set File Permissions

File permissions control who can read and write files. Apache needs specific permissions to serve your wiki and write uploads:

# Set ownership to Apache user
sudo chown -R www-data:www-data /var/www/bookstack

# Set basic permissions for files and folders
sudo find /var/www/bookstack -type d -exec chmod 755 {} \;
sudo find /var/www/bookstack -type f -exec chmod 644 {} \;

# Set writable permissions for specific folders
sudo chmod -R 775 /var/www/bookstack/storage
sudo chmod -R 775 /var/www/bookstack/bootstrap/cache
sudo chmod -R 775 /var/www/bookstack/public/uploads

This gives Apache:

  • Read access to all files
  • Write access to storage (for logs and cache)
  • Write access to uploads (for user-uploaded images)

Configure Firewall

If your server has a firewall, you need to allow web traffic to reach BookStack:

# Allow HTTP and HTTPS traffic
sudo ufw allow 'Apache'

# Enable firewall if not already enabled
sudo ufw enable

This opens ports 80 (HTTP) and 443 (HTTPS) so people can access your wiki from the internet.

Access BookStack

Open your web browser and go to your server’s address:

http://your-domain.com

or if you’re using an IP address:

http://your-server-ip

You should see the BookStack login page. Use these default credentials:

Important: These are temporary credentials. Change them immediately after logging in by clicking your name in the top-right corner and selecting “My Account.”

Add SSL Security (Recommended)

SSL encrypts data between your users and the server, making your wiki secure. Let’s Encrypt provides free SSL certificates:

# Install Certbot (Let's Encrypt client)
sudo apt install certbot python3-certbot-apache -y

# Get SSL certificate (change your-domain.com to your domain)
sudo certbot --apache -d your-domain.com

Certbot will ask for your email and agree to terms. Choose to redirect HTTP to HTTPS when prompted.

After SSL is installed, update BookStack to use the secure URL:

# Edit the config file
sudo nano /var/www/bookstack/.env

Change the APP_URL to use https:

APP_URL=https://your-domain.com

Clear the cache so BookStack uses the new settings:

sudo -u www-data php artisan config:clear

Common Problems and Solutions

Here are solutions to problems you might encounter:

Can’t connect to database:

  • Check if MySQL is running: sudo systemctl status mysql
  • Verify your database password in the .env file matches what you set
  • Make sure the database user was created correctly

Permission errors:

  • Reset file ownership: sudo chown -R www-data:www-data /var/www/bookstack
  • Check that storage and uploads folders have write permissions

500 Error (Internal Server Error):

  • Check Apache error log: sudo tail -f /var/log/apache2/error.log
  • Make sure mod_rewrite is enabled: sudo a2enmod rewrite
  • Verify your virtual host configuration is correct

Can’t upload files:

  • Check storage folder permissions: sudo chmod -R 775 /var/www/bookstack/storage
  • Make sure the uploads directory exists and is writable

SSL certificate issues:

  • Verify your domain points to your server’s IP address
  • Check that ports 80 and 443 are open in your firewall
  • Make sure Certbot completed without errors

Conclusion

You now have BookStack running on your Ubuntu server. You can create books, add chapters and pages, and invite users to collaborate on your wiki.

Remember to:

  • Change the default admin password immediately
  • Keep your system updated with sudo apt update && sudo apt upgrade
  • Make regular backups of your database and files
  • Monitor your server’s disk space and performance

BookStack is now ready to help you organize and share your documentation. Start by creating your first book and exploring the features like user management, themes, and page templates!

Account services are unavailable until the production backend is configured.