René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Issues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2","articleBody":"### Is there an existing issue for this?\n\n- [x] I have searched the existing issues\n\n### Current Behavior\n\nIssues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2\nHello team,\nI was attempting to set up BookStack using your Docker image (linuxserver/bookstack:latest) on a Windows 11 machine running Docker Desktop with WSL2 integration.\nI 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.\nThe problems and solutions were:\n1. Missing APP_KEY caused application halt\nThe 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.\n    Error message: The application key is missing, halting init!\n    Solution: The key must be manually generated and added to the docker-compose.yml file before deployment.\n2. Inconsistent database environment variable names\nThe documentation/examples often use DB_USER and DB_PASS, but the linuxserver/bookstack image specifically expects different variable names, leading to authentication errors.\n    Error message: Access denied for user 'database_username'@... (using password: YES)\n    Solution: The variables must be named DB_USERNAME and DB_PASSWORD.\n3. Windows Volume Permissions (500 Internal Server Error)\nAfter 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.\n\n    Error message: \"An unknown error occurred\" on the web page; logs showed a truncated Laravel exception.\n    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).\nThe final, working docker-compose.yml file structure (with corrected variables and key) looked like this:\nyaml\n\nversion: \"3.8\"\nservices:\n  bookstack:\n    image: linuxserver/bookstack:latest\n    container_name: bookstack\n    environment:\n      # ... other vars\n      - APP_KEY=base64:imKs0ZgKNOF2W9Kiiq+8gDUqkRWBwh1mzOjrSgV/ntk= # Must be present\n      - DB_USERNAME=bookstack # Correct name\n      - DB_PASSWORD=bookstackpass # Correct name\n      # ...\n# ... db service definition\nUpdating the official documentation or providing a robust Windows/WSL-specific guide might prevent these common roadblocks.\nThanks for the great work on the image!\nBest regards,\nDavi\n\n\n### Expected Behavior\n\n_No response_\n\n### Steps To Reproduce\n\nwindows 11 com docker \n\n### Environment\n\n```markdown\n- OS:Win 11\n- How docker service was installed:via site\n```\n\n### CPU architecture\n\nx86-64\n\n### Docker creation\n\n```bash\nIssues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2\nHello team,\nI was attempting to set up BookStack using your Docker image (linuxserver/bookstack:latest) on a Windows 11 machine running Docker Desktop with WSL2 integration.\nI 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.\nThe problems and solutions were:\n1. Missing APP_KEY caused application halt\nThe 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.\n    Error message: The application key is missing, halting init!\n    Solution: The key must be manually generated and added to the docker-compose.yml file before deployment.\n2. Inconsistent database environment variable names\nThe documentation/examples often use DB_USER and DB_PASS, but the linuxserver/bookstack image specifically expects different variable names, leading to authentication errors.\n    Error message: Access denied for user 'database_username'@... (using password: YES)\n    Solution: The variables must be named DB_USERNAME and DB_PASSWORD.\n3. Windows Volume Permissions (500 Internal Server Error)\nAfter 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.\n\n    Error message: \"An unknown error occurred\" on the web page; logs showed a truncated Laravel exception.\n    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).\nThe final, working docker-compose.yml file structure (with corrected variables and key) looked like this:\nyaml\n\nversion: \"3.8\"\nservices:\n  bookstack:\n    image: linuxserver/bookstack:latest\n    container_name: bookstack\n    environment:\n      # ... other vars\n      - APP_KEY=base64:imKs0ZgKNOF2W9Kiiq+8gDUqkRWBwh1mzOjrSgV/ntk= # Must be present\n      - DB_USERNAME=bookstack # Correct name\n      - DB_PASSWORD=bookstackpass # Correct name\n      # ...\n# ... db service definition\nUpdating the official documentation or providing a robust Windows/WSL-specific guide might prevent these common roadblocks.\nThanks for the great work on the image!\nBest regards,\nDavi\n```\n\n### Container logs\n\n```bash\nIssues setting up BookStack using linuxserver/bookstack image on Windows 11/Docker/WSL2\nHello team,\nI was attempting to set up BookStack using your Docker image (linuxserver/bookstack:latest) on a Windows 11 machine running Docker Desktop with WSL2 integration.\nI 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.\nThe problems and solutions were:\n1. Missing APP_KEY caused application halt\nThe 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.\n    Error message: The application key is missing, halting init!\n    Solution: The key must be manually generated and added to the docker-compose.yml file before deployment.\n2. Inconsistent database environment variable names\nThe documentation/examples often use DB_USER and DB_PASS, but the linuxserver/bookstack image specifically expects different variable names, leading to authentication errors.\n    Error message: Access denied for user 'database_username'@... (using password: YES)\n    Solution: The variables must be named DB_USERNAME and DB_PASSWORD.\n3. Windows Volume Permissions (500 Internal Server Error)\nAfter 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.\n\n    Error message: \"An unknown error occurred\" on the web page; logs showed a truncated Laravel exception.\n    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).\nThe final, working docker-compose.yml file structure (with corrected variables and key) looked like this:\nyaml\n\nversion: \"3.8\"\nservices:\n  bookstack:\n    image: linuxserver/bookstack:latest\n    container_name: bookstack\n    environment:\n      # ... other vars\n      - APP_KEY=base64:imKs0ZgKNOF2W9Kiiq+8gDUqkRWBwh1mzOjrSgV/ntk= # Must be present\n      - DB_USERNAME=bookstack # Correct name\n      - DB_PASSWORD=bookstackpass # Correct name\n      # ...\n# ... db service definition\nUpdating the official documentation or providing a robust Windows/WSL-specific guide might prevent these common roadblocks.\nThanks for the great work on the image!\nBest regards,\nDavi\n```","author":{"url":"https://github.com/davi-jorge-art","@type":"Person","name":"davi-jorge-art"},"datePublished":"2025-12-08T13:54:50.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/279/docker-bookstack/issues/279"}