BookStack VPS Migration & Setup Documentation

Summary

This documentation outlines the successful migration of a self-hosted BookStack instance from a local Proxmox environment to a cloud-hosted VPS. The goal was to maintain all user data, uploaded content, and configuration with minimal downtime.

🔗 Live Instance: https://docs.natenetworks.com

🏗️ Technologies Used

Infrastructure

• Host Provider: Hostinger VPS

• Operating System: Ubuntu Server 22.04 LTS

• Architecture: 64-bit KVM VPS

Core Stack (LAMP)

• Web Server: Apache 2

• Database: MariaDB (MySQL-compatible)

• PHP: 8.2 with required extensions

• Application: BookStack v24.02.2 (Laravel-based)

Domain Configuration

• DNS: A record for docs.natenetworks.com pointing to VPS public IP

• URL Configuration: Set in .env and updated via artisan command

Tools Used

• SSH Client: PuTTY

• SFTP Client: WinSCP

• Source Control: Git

• PHP Dependency Manager: Composer

• Laravel CLI: Artisan

🚀 Migration Process

1. VPS Preparation

Logged into the VPS via SSH and installed required packages:

sudo apt update && sudo apt upgrade -y
sudo apt install apache2 mariadb-server php8.2 php8.2-common php8.2-cli php8.2-mbstring php8.2-curl php8.2-xml php8.2-mysql unzip git curl composer

2. BookStack Deployment

Cloned the official BookStack repository:

sudo git clone https://github.com/BookStackApp/BookStack.git /var/www/bookstack
cd /var/www/bookstack
git checkout 24.02.2

Installed PHP dependencies:

composer install --no-dev --optimize-autoloader

Set correct file permissions:

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

3. Configuration

• Restored .env file from backup

• Updated APP_URL to: https://docs.natenetworks.com

• Verified required PHP extensions

• Ensured Apache service was active

4. Database Setup

• Created database and user credentials for BookStack

• Restored MySQL dump from local backup:

mysql -u bookstack -p bookstack < /tmp/bookstack.backup_5_3_25.sql

5. File Migration

Uploaded archive of uploaded files and customizations via SFTP, then extracted:

tar -xzf /tmp/bookstack-files-backup_5_3_25.tar.gz -C /var/www/bookstack

6. Laravel Maintenance Commands

Cleared and rebuilt application cache:

php artisan config:clear
php artisan cache:clear
php artisan view:clear

Updated stored URLs in the database:

php artisan bookstack:update-url http://192.168.1.236 https://docs.natenetworks.com

7. Final Testing

Restarted Apache and verified everything was operational:

sudo systemctl restart apache2

• Public site loaded successfully

• All pages, users, and uploads migrated cleanly

• Admin accounts remained intact

🧾 Notes

• All user and admin accounts retained post-migration

• SQL and file backups preserved externally

• Public/private visibility was maintained

• SMTP email is not currently configured (.env uses defaults)

Migration Date: May 4th, 2025
Lead Engineer: Nathaniel Nash
Environment: Production (Public Access)