Skip to main content

BookStack VPS Migration & Setup Documentation

BookStack

Summary

VPS Migration & Setup Documentation

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.

The

πŸ”— 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: Version 8.2 with required extensions

    BookStack:

  • 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 Artisanartisan command


    Access

    &

Tools

 Used

  • SSH Client: PuTTY

  • SFTP Client: WinSCP

  • Source Control: Git

  • PHP Dependency Manager: Composer

    BookStack

  • Laravel CLI: Artisan

    (Laravel
  • CLI)


πŸš€ 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:

GitHub:

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:

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 localbackup

    backup.

    Set
  • Updated APP_URL toto: https://docs.natenetworks.com.

    com

  • Verified required PHP extensions

    were
  • installed
  • and

    Ensured Apache service was running.


    active


4. Database Setup

  • Created and configured bookstack database and user.

    user credentials for BookStack

  • Restored SQLMySQL dump:

    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
  • all
  • user

    All datapages, users, and uploads intact.

    Notes

    migrated cleanly

  • Admin and user accounts remained intact


🧾 Notes

  • All user and admin accounts retained post-migration.

    migration

  • SQL and file backups were preserved off-premexternally

    and
  • used
  • to recover data.

    Public/private page visibility remainedwas unchanged.

    Nomaintained

    mail
  • system
  • SMTP email is not currently configured (SMTP.env valuesuses remaindefaults)

    default).


βœ… Next Steps

  •  Enable HTTPS via (Let’s Encrypt or equivalent.

    SetCertbot)

    up
  • automatic
  •  Schedule automated backups (e.g., via cron or rsyncSyncthing)

    to
  • offsite
  • storage).

     Configure SMTP mail settings

    for
  • email
  • notifications.

    Harden

     Apply 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.