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

[davi-jorge-art]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

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

Expected Behavior

No response

Steps To Reproduce

windows 11 com docker

Environment

- OS:Win 11
- How docker service was installed:via site

CPU architecture

x86-64

Docker creation

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

Container logs

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

[github-actions]

Thanks for opening your first issue here! Be sure to follow the relevant issue templates, or risk having this issue marked as invalid.

[aptalca]

Missing APP_KEY caused application halt

The readme clearly states Unless a parameter is flaged as 'optional', it is mandatory and a value must be provided. right above the sample compose yaml and docker run. APP_KEY var is not marked as optional: https://github.com/linuxserver/docker-bookstack?tab=readme-ov-file#usage

Inconsistent database environment variable names

Tha db variables our image uses are correctly listed in the readme, and are not marked optional so they have to be set as listed in our image readme.

Windows Volume Permissions (500 Internal Server Error)

That's specific to running linux containers in docker desktop on Windows and not specific to this image. Our general recommendation is to use linux paths in WSL (not ntfs), but that's beyond the scope of this image's readme.