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

[davi-jorge-art]

Is there an existing issue for this?

• [x] 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