BookStack migrate to new server: step-by-step guide
Database backup, file transfer, configuration. All the steps. Plus: why teams upgrade to real-time collaboration during migration.
Why migrate BookStack?
You are moving BookStack. Maybe to fresh infrastructure. Maybe away from outdated hardware. Maybe to a hosted option because DIY is burning your time.
Whatever the reason, migration is manual work. Downtime is required. Data loss is a real risk if you skip a step.
This guide covers the full process: what to back up, how to restore it, what breaks, and how to fix it. Then we show you why teams use this migration window to upgrade to something better.
How to migrate BookStack to a new server
Five core steps to move your BookStack installation to new infrastructure. Follow in order. Test at each stage.
Backup your database
Export your BookStack database (MySQL or MariaDB) using mysqldump or your database management tool. Store the backup securely offline. This is your safety net if restore fails.
Backup your files
Copy all user-uploaded files: images, attachments, custom themes. BookStack stores these in /storage/uploads. Use rsync or tar to preserve file permissions and ownership.
Install BookStack on the new server
Set up the new server with PHP 8.2+, MySQL 8.0+ or MariaDB 10.6+, Git, Composer, and a web server. Follow BookStack's official installation documentation for your OS (Ubuntu 22.04 LTS recommended).
Restore database and files
Import your database backup into the new MySQL instance. Copy uploaded files into /storage/uploads on the new server. Update the .env file with new database credentials and the APP_URL pointing to your domain.
Test and update DNS
Test BookStack on the new server by visiting its IP address or temporary hostname. Verify all pages, images, and file attachments load correctly. Update your DNS records to point your domain to the new server. Decommission the old server once verified.
What carries over in BookStack migration
Carries over without reconfiguration:
- All pages, chapters, books, shelves (complete database content)
- User-uploaded images and file attachments
- Page comments and version history
- Page tags and labels
- Search indexes
Carries over, needs reconfiguration:
- User accounts (passwords reset required if using email authentication)
- LDAP/SAML integration (re-authenticate, but credentials remain the same)
- Custom themes (CSS carries over, verify rendering on new server)
- API tokens (regenerate for security)
- Role-based permissions (preserved in database, verify access after restore)
Does not carry over (start fresh):
- Scheduled backups (set up on new server)
- SSL certificate (install new cert or use auto-renewal)
- Web server configuration (Nginx/Apache vhost, site-specific)
- ActivityLog entries (not critical, can export before if needed)
- Cron jobs (reconfigure if used for maintenance)
Reality check: The data moves cleanly. Testing takes 2-4 hours. Expect small fixes: broken cross-page links if hostnames changed, image path updates, permission edge cases.
Common migration mistakes (and how to avoid them)
1. Downtime during migration
You cannot migrate live. The database must be locked during backup and restore. Typical downtime window: 4-8 hours depending on database size and file count. Plan for off-hours. Notify users in advance. No workaround exists for standard BookStack.
2. URL changes break internal links
If your new BookStack has a different hostname or path, internal links and API calls may break. BookStack stores absolute URLs in the database for some content types. Use a database find-and-replace (carefully) to update them after restore, or implement HTTP redirects from old domain to new.
3. Database version incompatibility
BookStack requires MySQL 8.0+ or MariaDB 10.6+. If you restore from an older version, migration will fail. Test the restore on a staging server first. After successful restore, always run: php artisan migrate
4. File permissions lost during copy
When copying /storage/uploads, permissions and ownership must be preserved for the web server to read files. Use rsync with the correct flags: rsync -a --chown=www-data:www-data /old/path/uploads /new/path/uploads
5. Forgetting the .env file
Your .env contains database credentials, encryption keys, and app secrets. It is not in version control. Copy it manually to the new server and update database host, port, and password if credentials changed. Failing to do this is the most common blocker.
Plus infrastructure cost: hands-off with Opsily
DIY BookStack migration: 8-40 person-hours (or pay DevOps). Infrastructure: 30-100/month baseline. Opsily managed migration: flat transparent pricing, 24-hour migration window, zero downtime, automated backups included.
See managed hosting optionsWhy choose Opsily for BookStack migration (or upgrade to Docmost)
Migration is a moment of truth. You are already accepting downtime and effort. Use it to upgrade to a better platform.
Hands-off migration
We handle database backup, restore, file transfer, .env configuration, and DNS cutover. You provide old server credentials. We execute the migration in a 24-hour window with zero downtime. Done.
Real-time collaboration with Docmost
If you upgrade to Docmost during migration, your team gets real-time editing (see other users' cursors), modern block-based editor, and built-in diagrams. No more slow page refresh. No more edit conflicts.
Security and backups included
German data centers, daily encrypted backups stored offsite, SSL auto-renewal. 99.9% uptime SLA. Monitoring and patching are our job, not yours.
Built for teams who need reliability
Managed Docmost hosting starts at:
Choose the plan that fits your team size. All plans include German data centers, daily encrypted backups, SSL auto-renewal, and 99.9% uptime SLA.
Loading pricing...
Trust & Compliance
Your data in secure hands.
GDPR Compliant
Full GDPR compliance with EU data residency in Germany. Your data stays in the EU at all times.
Daily Encrypted Backups
Automatic encrypted backups every 24 hours. Restore to any point in time. Backups stored securely in German data centers.
Transparent Pricing
No hidden fees. No contact-sales gatekeeping. Per-user pricing. See exactly what you pay upfront.
Automated Monitoring
24/7 system monitoring and alerting. Automatic patching and maintenance. Zero downtime updates.
Frequently Asked Questions
The actual database transfer and file copy takes 1-4 hours depending on database size and file count. Testing and troubleshooting add 2-4 hours. Total DIY project: expect 8-40 person-hours of work. With Opsily managed migration, we handle the entire process in a 24-hour window with zero downtime.
Ready to migrate? Or upgrade to real-time collaboration?
Start your BookStack migration to a new server. Or upgrade to Docmost on Opsily and skip the DevOps entirely.