BookStack VPS Migration & Setup Documentation
BookStack
Summary
This documentdocumentation outlines the successful migration of a self-hosted BookStack instance from a local Proxmox environment to a cloud-hosted VPS. The migrationgoal involvedwas restoringto maintain all files, user data, uploaded content, and configuration to ensure a seamless transition with minimal downtime.
π endLive resultInstance: is a fully operational, public-facing instance of BookStack accessible at https://docs.natenetworks.com.
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:
Version8.2 with required extensionsBookStack: -
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 viaArtisanartisan
commandAccess&
Tools
Used
-
SSH Client: PuTTY
-
SFTP Client: WinSCP
-
Source Control: Git
-
PHP Dependency Manager: Composer
BookStack -
Laravel CLI: Artisan
(Laravel
π Migration Process
1. VPS Preparation
Logged into the Hostinger VPS via SSH.UpdatedSSH and installed necessaryrequired packages:
sudo apt update && sudo apt upgrade
-y
sudo apt install apache2 mariadb-server php8.2 php8.2-extensions...
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 fromrepository:
sudo git clone https://github.com/BookStackApp/BookStack.git /var/www/bookstack
cd /var/www/bookstack &&
git checkout 24.02.2
Installed dependenciesPHP withdependencies:
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 fromlocalbackupbackup.Set -
Updated
APP_URL
toto:https://docs.natenetworks.
com.
com -
Verified required PHP extensions
were -
andEnsured Apache service was
running.
active
4. Database Setup
-
Created
and configured bookstackdatabase anduser.
user credentials for BookStack -
Restored
SQLMySQLdump:
dump from local backup:
mysql -u bookstack -p bookstack < /tmp/bookstack.backup_5_3_25.sql
5. File Migration
Uploaded .tar.gzarchive fileof containinguploaded BookStack uploadsfiles and themescustomizations usingvia WinSCP.ExtractedSFTP, tothen /var/www/bookstack:
extracted:
tar -xzf /tmp/bookstack-files-backup_5_3_25.tar.gz -C /var/www/bookstack
6. Laravel Maintenance Commands
Cleared and rebuilt config andapplication cache:
php artisan config:clear
php artisan cache:clear
php artisan view:clear
Updated stored URLs:
URLs in the database:
php artisan bookstack:update-url http://192.168.1.236 https://docs.natenetworks.com
7. Final Testing
Restarted Apache:
Apache and verified everything was operational:
sudo systemctl restart apache2
Verified
-
Public site loaded successfully
with -
userAll
datapages, users, and uploadsintact.Notes
migrated cleanly -
Admin
and useraccounts remained intact
π§Ύ Notes
-
All user and admin accounts retained post-
migration.
migration -
SQL and file backups
werepreservedoff-premexternallyand -
to recover data.Public/private
pagevisibilityremainedwasunchanged.Nomaintainedmail -
SMTP email is not currently configured (
SMTP.env
valuesusesremaindefaults)default).
β
Next Steps
-
Enable HTTPS
via(Letβs Encrypt orequivalent.SetCertbot)up -
Schedule automated backups (
e.g., viacron orrsyncSyncthing)to -
storage).Configure SMTP mail settings
for -
notifications.HardenApply server
securityhardening (fail2ban,UFW,ufw,Fail2Ban, regular package 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.