Issues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2

[davi-jorge-art]

Describe the Bug

Issues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2
Hello team,
I was attempting to set up BookStack using your Docker image (linuxserver/bookstack:latest) on a Windows 11 machine running Docker Desktop with WSL2 integration.
I encountered a few issues with existing documentation/guides that caused initial setup failures. I believe addressing these points could help future users on similar environments.
The problems and solutions were:

1. Missing APP_KEY caused application halt
   The main container failed to initialize because the APP_KEY environment variable was missing. The container entrypoint does not seem to auto-generate this if it's absent.
   Error message: The application key is missing, halting init!
   Solution: The key must be manually generated and added to the docker-compose.yml file before deployment.

2. Inconsistent database environment variable names
   The documentation/examples often use DB_USER and DB_PASS, but the linuxserver/bookstack image specifically expects different variable names, leading to authentication errors.
   Error message: Access denied for user 'database_username'@... (using password: YES)
   Solution: The variables must be named DB_USERNAME and DB_PASSWORD.

3. Windows Volume Permissions (500 Internal Server Error)
   After fixing the database connection, I encountered a generic "An unknown error occurred" error (HTTP 500) because the container could not write to the persistent volumes created by Docker on the Windows file system.

   Error message: "An unknown error occurred" on the web page; logs showed a truncated Laravel exception.
   Solution: The volumes needed to be cleared completely using docker-compose down -v and then recreated by running docker-compose up -d to ensure correct permissions for the container's UID/GID (1000/1000).
   The final, working docker-compose.yml file structure (with corrected variables and key) looked like this:
   yaml

version: "3.8"
services:
bookstack:
image: linuxserver/bookstack:latest
container_name: bookstack
environment:
# ... other vars
- APP_KEY=base64:imKs0ZgKNOF2W9Kiiq+8gDUqkRWBwh1mzOjrSgV/ntk= # Must be present
- DB_USERNAME=bookstack # Correct name
- DB_PASSWORD=bookstackpass # Correct name
# ...

... db service definition

Updating the official documentation or providing a robust Windows/WSL-specific guide might prevent these common roadblocks.
Thanks for the great work on the image!
Best regards,
Davi

Steps to Reproduce

Instalation via docker

Expected Behaviour

Access the app

Screenshots or Additional Context

No response

Browser Details

No response

Exact BookStack Version

25.11.5

[ssddanbrown]

Thanks for the feedback, but the linuxserver docker project is not an official part of the project we control.
Therefore I'm going to close this off.

We do provide an example compose stack, but I don't think those issues are relevant to that.

I'm not sure if passing the info to the linuxserver project would help either, as their own documentation already states the correct env variables to use, and how to generate the required APP_KEY, while the windows permission error is scenario/environment specific.

[davi-jorge-art]

Again, thank you very, very much for the rapid response.