Bookstack Project Documentation
BookStack VPS Migration & Setup Documentation
Summary
This document outlines the successful migration of a self-hosted BookStack instance from a local Proxmox environment to a cloud-hosted VPS. The migration involved restoring all files, user data, and configuration to ensure a seamless transition with minimal downtime. The end result is a fully operational, public-facing instance of BookStack accessible at 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: Version 8.2 with required extensions
BookStack: v24.02.2 (Laravel-based)
Domain Configuration
DNS: A record for docs.natenetworks.com pointing to VPS IP
URL Configuration: Set in .env and updated via Artisan command
Access & Tools
SSH Client: PuTTY
SFTP Client: WinSCP
Source Control: Git
PHP Dependency Manager: Composer
BookStack CLI: Artisan (Laravel CLI)
Migration Process
1. VPS Preparation
Logged into the Hostinger VPS via SSH.
Updated and installed necessary packages:
sudo apt update && sudo apt upgrade
sudo apt install apache2 mariadb-server php8.2 php8.2-extensions...
2. BookStack Deployment
Cloned BookStack from GitHub:
sudo git clone https://github.com/BookStackApp/BookStack.git /var/www/bookstack
cd /var/www/bookstack && git checkout 24.02.2
Installed dependencies with Composer:
composer install --no-dev --optimize-autoloader
Set permissions:
sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
3. Configuration
Restored .env file from local backup.
Set APP_URL to https://docs.natenetworks.com.
Verified PHP extensions were installed and Apache was running.
4. Database Setup
Created and configured bookstack database and user.
Restored SQL dump:
mysql -u bookstack -p bookstack < /tmp/bookstack.backup_5_3_25.sql
5. File Migration
Uploaded .tar.gz file containing BookStack uploads and themes using WinSCP.
Extracted to /var/www/bookstack:
tar -xzf /tmp/bookstack-files-backup_5_3_25.tar.gz -C /var/www/bookstack
6. Laravel Commands
Cleared and rebuilt config and cache:
php artisan config:clear
php artisan cache:clear
php artisan view:clear
Updated stored URLs:
php artisan bookstack:update-url http://192.168.1.236 https://docs.natenetworks.com
7. Final Testing
Restarted Apache:
sudo systemctl restart apache2
Verified site loaded successfully with all user data and uploads intact.
Notes
Admin and user accounts remained intact post-migration.
SQL and file backups were preserved off-prem and used to recover data.
Public/private page visibility remained unchanged.
No mail system is currently configured (SMTP values remain default).
Next Steps
Enable HTTPS via Let’s Encrypt or equivalent.
Set up automatic backups (e.g., via cron or rsync to offsite storage).
Configure SMTP settings for email notifications.
Harden server security (fail2ban, ufw, regular updates).
Migration Date: May 4th, 2025
Lead Engineer: Nathaniel Nash
Environment: Production (Public Access)
---
This entry should be updated if any changes are made to the server, database, or core BookStack configuration.