BookStack Deploy: Choose a Route & Plan Upkeep

This guide walks you through deploying BookStack, a free and open-source wiki platform, by first helping you choose the installation route that best fits your skills and server setup, then covering the ongoing upkeep tasks that keep it secure and running smoothly. You’ll learn the trade-offs between manual installation, Docker, and cloud marketplace images, and get a clear maintenance checklist.

What You’ll Need

• A server (VPS, dedicated, or even a Raspberry Pi) with at least 1GB RAM and 10GB storage.
• Root or sudo access to that server.
• A domain name (optional but recommended for production).
• Basic comfort with the command line.

Step-by-Step

1. Choose Your Install Route

BookStack can be installed in several ways. Your choice depends on your experience and how much control you want.

• Manual (PHP + MySQL + Composer) – Most control, best for learning, but requires more steps and manual updates.
• Docker (using the official image) – Easiest to deploy and update, isolates dependencies, great for production and development.
• Cloud Marketplace Image – One-click install on providers like DigitalOcean or AWS, but you inherit the provider’s maintenance choices and may have less flexibility.

For most users, Docker is recommended because it simplifies updates and reduces environment-specific issues. If you prefer a traditional LAMP stack, the manual route is fine.

2. Prepare Your Server

Update your server’s package list and install basic tools:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git unzip

If you’re going the manual route, also install PHP (8.1+), MySQL/MariaDB, and Nginx or Apache. For Docker, you only need Docker and Docker Compose.

3. Manual Installation (if chosen)

1. Install PHP and required extensions: sudo apt install php8.1-fpm php8.1-mysql php8.1-gd php8.1-xml php8.1-mbstring php8.1-curl php8.1-zip
2. Install MySQL: sudo apt install mysql-server and create a database and user.
3. Download BookStack: git clone https://github.com/BookStackApp/BookStack.git /var/www/bookstack
4. Set permissions: sudo chown -R www-data:www-data /var/www/bookstack
5. Copy .env.example to .env and edit database credentials, app URL, and generate an app key.
6. Run composer install --no-dev and php artisan migrate.
7. Configure your web server to point to the public directory.

4. Docker Installation (if chosen)

1. Create a directory: mkdir bookstack && cd bookstack
2. Create a docker-compose.yml file with services for bookstack and db (MySQL). Use the official linuxserver/bookstack image.
3. Set environment variables: APP_URL, DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD.
4. Run docker-compose up -d.
5. Access your site at http://your-server-ip. Default login is admin@admin.com / password (change immediately).

5. Configure Web Server and SSL

For both routes, set up a reverse proxy (Nginx or Caddy) to handle HTTPS. Use Let’s Encrypt for free SSL certificates. For Docker, you can use a reverse proxy container like Traefik or Nginx Proxy Manager.

6. Plan for Upkeep

Regular maintenance is essential for security and stability. Set a recurring calendar reminder for these tasks:

• Weekly: Check for BookStack updates (GitHub releases or Docker image updates).
• Monthly: Back up your database and uploaded files. Test restoring a backup.
• Quarterly: Review user accounts and permissions. Remove inactive users.
• As needed: Apply security patches promptly. Monitor logs for errors.

7. Update BookStack

For manual installs, backup first, then pull the latest code, run composer install --no-dev, php artisan migrate, and clear caches. For Docker, simply pull the latest image and recreate the container – your data persists in volumes.

Common Mistakes

• Forgetting to change the default admin password – This is the most common security hole.
• Not setting the correct APP_URL – Causes broken links and asset loading issues.
• Skipping database backups – You will lose data eventually.
• Using HTTP in production – Always use HTTPS.
• Ignoring file permissions – In manual installs, wrong ownership leads to errors.

Tips

• Use a dedicated database user with limited privileges for BookStack.
• Enable two-factor authentication (2FA) for admin accounts.
• Set up automated backups using cron or a tool like restic.
• Use a CDN or caching layer if you expect heavy traffic.
• Keep your server OS updated too.

Troubleshooting

• Blank page after install – Check PHP error logs (/var/log/php8.1-fpm.log). Common causes: missing extensions, wrong file permissions, or incorrect .env settings.
• Cannot connect to database – Verify database host, port, credentials, and that the database service is running.
• Assets not loading (CSS/JS) – Ensure APP_URL matches your actual domain and run php artisan view:clear.
• Docker container exits – Check logs with docker-compose logs. Usually a misconfigured DB_HOST or missing volume.
• Login issues – Clear browser cache and cookies, and ensure the session driver is set correctly in .env.

Frequently Asked Questions

Can I install BookStack on shared hosting?

It’s possible but not recommended because you need to run Composer and migrations, which often require SSH access. Use a VPS or a Docker-capable host.

How do I update BookStack without losing my content?

Always backup first. Then follow the update steps for your install method. Your content is stored in the database and uploaded files, which are preserved if you don’t delete them.

Is Docker the best option for production?

Yes, Docker is a solid choice for production because it makes updates and rollbacks easier, and isolates dependencies. Just ensure you use volumes for persistent data.

Can I use SQLite instead of MySQL?

BookStack officially supports MySQL, MariaDB, and PostgreSQL. SQLite is not supported for production, so stick with one of those.

How do I change the default admin email and password?

Log in with the default credentials, then go to Settings > Users, edit the admin user, and set a new email and password. Also enable 2FA.

What should I do if I forget my admin password?

You can reset it via the command line: php artisan bookstack:reset-admin-password (manual) or docker exec -it <container> php artisan bookstack:reset-admin-password (Docker).

Related

• Four-Marketplace AI Listing Optimizer Architecture
• Claude for Startups Alternatives: Coding AI and Credits
• Fine-Tuning vs Prompting: A Practical Team Guide