Skip to main content

Deploying BookStack via CasaOS App Store

Environment Context:

  • Hostname: LinuxServer
  • OS: Ubuntu Server (CasaOS UI layer)
  • Hardware: Micro PC (7th-Gen Intel Core i5, 16GB DDR4 RAM, 256GB NVMe SSD)
  • Service: BookStack (BigBearCasaOS Repository)

1. Host OS Optimization

Before deploying database-heavy containers, ensure the host Ubuntu Server is configured to maintain the write endurance and performance of the 256GB NVMe SSD.

Connect to LinuxServer via SSH (or via the local KVM console) and enable the continuous TRIM timer:

sudo systemctl enable --now fstrim.timer

2. CasaOS Installation

To prevent volume overlap and network isolation issues, utilize the pre-configured application template from the CasaOS App Store.

  1. Navigate to the CasaOS web dashboard (http://192.168.0.160).
  2. Open the App Store.
  3. Search for and select BookStack (Developer: Dan Brown / BigBearCasaOS).
  4. Click Install.
  5. Crucial: Once the installation finishes, do not click the app icon yet. Proceed immediately to configuration.

3. Configuration & Routing Fixes

The default BigBear template contains a placeholder URL and uses port 8080, which often causes conflicts and results in a 500 Internal Server Error. These must be adjusted before the first boot.

  1. Click the three vertical dots (⋮) on the newly installed BookStack icon and select Settings.
  2. Update Web UI Port: At the top of the settings window, change the Web UI port from 8080 to a dedicated port (e.g., 6875).
  3. Update Host Port: Scroll down to the Port section. Change the Host port from 8080 to 6875. (Leave the Container port as 80).
  4. Fix App URL: Scroll down to the Environment Variables section. Locate the APP_URL key.
  5. Change the value from the literal placeholder http://[change to your IP]:8080 to the server's exact static IP and new port:
    • Value: http://192.168.0.160:6875
  6. Click the blue Save button.

4. Database Initialization

When the settings are saved, CasaOS will restart the container. BookStack's internal MariaDB container must now generate its base tables on the NVMe drive.

  • Wait exactly 60 to 120 seconds to allow the i5 processor to complete the initial database migrations.
  • Attempting to access the application before this completes may result in an incomplete database generation and a fatal crash loop.

5. First Login and Security Hook

Once initialization is complete, click the BookStack app icon on the CasaOS dashboard. You will be routed to the login screen.

  • Default Email: admin@admin.com
  • Default Password: password

Immediate Post-Install Action: Upon successful login, navigate to the administrator profile in the top right corner. Select Edit Profile, update the email address to your personal address, and change the password to a secure string to lock down the instance.

Back to top