Skip to main content

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)

No Comments
Back to top