mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-08 03:09:39 +03:00
Issues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2 #5538
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @davi-jorge-art on GitHub (Dec 8, 2025).
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:
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.
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.
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 commented on GitHub (Dec 8, 2025):
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 commented on GitHub (Dec 8, 2025):
Again, thank you very, very much for the rapid response.