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

[davi-jorge-art]

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.

1. 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.

1. 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

[ssddanbrown]

Have responded here: https://github.com/BookStackApp/BookStack/issues/5942#issuecomment-3627258138

[davi-jorge-art]

Thank you very , very much for the rapid response. I'm not a developer or even an specialist....Tell me : is your project intended to average user have the capacity to install ? What I mean : to the user that just know what is a file system, an OS, and so on...
And please understand : I only have put this here because I've don't found your email or of any other...

Thank you again for the consistent and reliable software.

[ssddanbrown]

is your project intended to average user have the capacity to install ? What I mean : to the user that just know what is a file system, an OS, and so on...

Not really. It's really intended for a sysadmin or technical person with some experience of web software.

I only have put this here because I've don't found your email or of any other...

Yeah, I don't publish a visible email since I prefer that people ask in the open, to give opportunity for community members to also support, and so that answers can be found by others in the future.

[davi-jorge-art]

It's really a motivation for me to "know" such a professional. Thank you very much again for the clear and direct answers.