DPTCloud
Back to articles
Technology Insight

How to Install BookStack on a VPS: Building a Centralized Documentation Wiki for Freelance Projects

May 29, 2026

Introduction: The Necessity of Centralized Documentation in Freelance Operations

In the modern freelance economy, managing complex projects with distributed teams requires seamless access to accurate information. As operations scale, relying on fragmented communication channels like chat apps, scattered cloud docs, or email threads inevitably leads to data silos, version control issues, and lost productivity. To maintain operational efficiency and deliver high-quality results, establishing a single source of truth is imperative.

BookStack is an exceptional, open-source, self-hosted wiki platform designed with an intuitive, hierarchical structure based on the analogy of Books, Chapters, and Pages. This makes it an ideal solution for internal documentation. By deploying BookStack on a Virtual Private Server (VPS), freelance businesses gain full control over their intellectual property, data privacy, and system configuration. This guide provides a comprehensive, production-ready walkthrough for installing BookStack on an Ubuntu-based VPS, ensuring your team has a secure, fast, and organized knowledge base.

---

Prerequisites and Infrastructure Preparation

Before initiating the installation process, ensure your environment meets the minimum technical specifications required for stable performance. While BookStack is highly optimized, adequate resource allocation prevents latency during concurrent user access.

System Requirements

  • Operating System: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS (Clean installation recommended).
  • Hardware: Minimum 1 vCPU, 1 GB RAM, and 20 GB SSD storage. For larger teams or heavy attachment usage, 2 vCPUs and 2 GB RAM are recommended.
  • Network: A public static IP address assigned to your VPS.
  • Domain Name: A registered domain or subdomain (e.g., wiki.yourdomain.com) with A records pointed to your VPS IP address.

Step 1: System Update and Initial Security Configuration

Connect to your VPS via SSH and update the package repository to ensure all existing system software is current. Run the following commands:

sudo apt update && sudo apt upgrade -y

Once the update completes, configure a basic firewall using UFW (Uncomplicated Firewall) to secure your server, allowing SSH, HTTP, and HTTPS traffic:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
---

Installing the LAMP/LEMP Stack Components

BookStack is built on the Laravel framework and requires a standard web serving stack. In this guide, we utilize the LEMP stack (Linux, Nginx, MySQL, PHP) for its superior performance, lower memory footprint, and high concurrency handling capabilities.

Step 2: Installing Nginx Web Server

Install the Nginx web server using the advanced package tool:

sudo apt install nginx -y

Verify that the Nginx service is active and running:

sudo systemctl status nginx

Step 3: Installing and Securing MySQL Database

BookStack relies on a relational database to store page content, user structures, and application configurations. Install MySQL Server:

sudo apt install mysql-server -y

Execute the security script to remove insecure default settings, disable remote root logins, and set a robust root password:

sudo mysql_secure_installation

Log into the MySQL prompt to create a dedicated database and user account for BookStack. Replace Secure_Password_Here with a strong, unique credential:

sudo mysql

Inside the MySQL interface, execute the following SQL statements:

CREATE DATABASE bookstack_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack_user'@'localhost' IDENTIFIED BY 'Secure_Password_Here';
GRANT ALL PRIVILEGES ON bookstack_db.* TO 'bookstack_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 4: Installing PHP and Required Extensions

BookStack requires PHP along with several specific extensions for handling XML, multi-byte strings, database communication, and image manipulation. Install PHP-FPM and the necessary extensions using the following command:

sudo apt install php-fpm php-mysql php-common php-curl php-mbstring php-xml php-gd php-bcmath php-tokenizer php-zip -y
---

Downloading and Configuring BookStack

With the core environment established, we proceed to download the BookStack source code via Git, install dependencies via Composer, and configure the application environment settings.

Step 5: Cloning the Source Code and Setting Permissions

Navigate to the standard web root directory and clone the official BookStack repository from GitHub:

cd /var/www
sudo git clone [https://github.com/BookStackApp/BookStack.git](https://github.com/BookStackApp/BookStack.git) bookstack
cd bookstack

To ensure the web server can read and write necessary session, cache, and upload files, assign correct ownership and permissions to the directory structure:

sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads

Step 6: Installing Composer and PHP Dependencies

Composer is the dependency manager for PHP applications. Download and install Composer globally:

cd ~
curl -sS [https://getcomposer.org/installer](https://getcomposer.org/installer) | php
sudo mv composer.phar /usr/local/bin/composer

Navigate back to your BookStack directory and run the deployment installation to pull down all framework dependencies:

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

Step 7: Environment Configuration (.env)

BookStack utilizes an .env file to manage environmental variables. Duplicate the provided configuration template:

sudo -u www-data cp .env.example .env

Open the file with a text editor (such as Nano) to input your specific configuration details:

sudo nano .env

Modify the following key parameters to match your domain and database credentials:

# Application URL
APP_URL=[https://wiki.yourdomain.com](https://wiki.yourdomain.com)

# Database Details
DB_DATABASE=bookstack_db
DB_USER=bookstack_user
DB_PASSWORD=Secure_Password_Here

Save and close the file (Press Ctrl+O, Enter, then Ctrl+X).

Step 8: Generating Application Key and Database Migration

Generate a unique application encryption key, which secures user sessions and encrypted data tokens:

sudo -u www-data php artisan key:generate

Next, populate the database schema by running the built-in database migrations. This setup process creates all necessary tables and default administration records:

sudo -u www-data php artisan migrate --force
Security Note: Upon successful completion of the database migration, BookStack generates a default administrative user account. The default credentials are username: [email protected] and password: password. It is critical to alter these credentials immediately after your first login.
---

Web Server Integration and SSL Deployment

To expose your BookStack installation securely to the web, you must configure Nginx as a reverse proxy/web server and provision an SSL certificate to encrypt transport-layer data.

Step 9: Nginx Server Block Configuration

Create a dedicated Nginx configuration file for your BookStack instance:

sudo nano /etc/nginx/sites-available/bookstack

Insert the following configuration, ensuring you adjust the server_name and PHP-FPM socket version to match your specific setup:

server {
    listen 80;
    server_name wiki.yourdomain.com;
    root /var/www/bookstack/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }

    client_max_body_size 50M;
}

Enable the site configuration by creating a symbolic link to the sites-enabled directory, then test the Nginx configuration syntax for correctness:

sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
sudo nginx -t

If the test returns successful, restart the Nginx service to apply changes:

sudo systemctl restart nginx

Step 10: Enforcing HTTPS via Let's Encrypt SSL

Operating an internal business wiki over unencrypted HTTP exposes sensitive credentials and project data to packet sniffing. Use Certbot to acquire and maintain a free, automated Let's Encrypt SSL certificate:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d wiki.yourdomain.com

Follow the interactive prompts to complete the certificate generation. Select the option to automatically redirect all HTTP traffic to HTTPS, ensuring continuous encryption across your entire documentation platform.

---

Post-Installation and Best Practices for Freelancers

With the technical deployment finalized, access your instance via [https://wiki.yourdomain.com](https://wiki.yourdomain.com). Log in using the default credentials noted in Step 8, navigate immediately to the user profile settings, and modify both the email address and password to secure the administrator account.

Optimizing BookStack for Freelance Projects

To maximize the utility of your new knowledge management tool, consider implementing the following structural paradigms:

  • Books as Client Portals: Dedicate an entire Book to each major client or freelance project. This isolates project contexts cleanly.
  • Chapters as Lifecycle Phases: Within a Book, utilize Chapters to represent phases like Discovery & Requirements, Architecture & Design, API Documentation, and Handover Protocols.
  • Granular Role Permissions: If you work with external contractors or client stakeholders, utilize BookStack’s robust Role and Asset Permissions system to grant access selectively to specific Books while hiding internal operational frameworks.

By establishing this scalable architecture on your own VPS, you ensure low-latency access, absolute ownership over your business data, and a highly professional collaborative environment that drives project success.

How to Install BookStack on a VPS: Building a Centralized Documentation Wiki for Freelance Projects | DPTCloud