# 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](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:

```bash
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:

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

```

Installed PHP dependencies:

```bash
composer install --no-dev --optimize-autoloader

```

Set correct file permissions:

```bash
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:

```bash
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:

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

```

---

#### 6. Laravel Maintenance Commands

Cleared and rebuilt application cache:

```bash
php artisan config:clear
php artisan cache:clear
php artisan view:clear

```

Updated stored URLs in the database:

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

```

---

#### 7. Final Testing

Restarted Apache and verified everything was operational:

```bash
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)