[BUG] dotenv file values are not set according to the Docker configuration file

[merrime-n]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

I have got the latest Bookstack version from Dockerhub and I use it in a Docker Compose configuration file to deploy Bookstack on a machine where no existing instance is available (I am therefore not updating my Bookstack, it's a fresh installation) so that the dotenv (.env) file is not present.

After the container deployment is complete, when I check the container files and the dotenv file is not populated. When I updated my existing bookstack instance (v24.05.4), it worked fine, possibly because of the presence of a dotenv file with values.

It seems like the Docker image (linuxserver/bookstack:24.10.20241028, linuxserver/bookstack:version-v24.10 or ghcr.io/linuxserver/bookstack:24.10.20241028) is buggy and cannot set the values (database credentials, API base key, etc.)

Expected Behavior

I expect the configuration file to set the environment variables upon container deployment.

Steps To Reproduce

1. Get the newest image
2. Fresh install a Bookstack instance
3. Check the logs
4. The first problem occurs because of API base key not being available
5. Check the .env file
6. It's empty!

Environment

- OS: Ubuntu Server 22.04
- Bookstack is deployed using Docker Compose

CPU architecture

x86-64

Docker creation

services:
  bookstack:
    # image: docker.io/linuxserver/bookstack:24.05.4
    image: docker.io/linuxserver/bookstack:24.10.20241028
    container_name: bookstack
    environment:
      PUID: 1000
      PGID: 1000
      APP_URL: http://my_url:6875
      DB_HOST: bookstack_db
      DB_USER: bookstack_user
      DB_PASS: db_password
      DB_DATABASE: bookstackdb

    volumes:
      - data:/config
    ports:
      - 6875:80
    restart: unless-stopped
    networks:
      - app-network

Container logs

An application key is missing, halting init!
You can generate a key with: docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

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

[mbellitti]

I'm having the same issue, also on a fresh install of the latest bookstack image.

[thespad]

Nothing is "buggy", we switched to defaulting to environment variable-based configuration a while ago. If you had an existing .env we didn't touch it but otherwise we no longer use it and simply copy the example file to /config/www/.env . If you wish to use the .env file as your means of configuration you can add settings to it yourself but note that any environment variables you've set will supersede the values in the .env file.

The specific issue OP is having is due to not following the current readme (presumably copy/pasting from an existing install) and therefore not setting all of the required environment variables.

[mbellitti]

Thank you for responding. It sounds like the problems is with the APP_KEY= variable (which is missing from OP's docker-compose.yml), should I generate that by hand and add it to my .env file? It's not clear from the README

[thespad]

No, you can just add it as an environment variable as with all the others:

https://github.com/linuxserver/docker-bookstack?tab=readme-ov-file#parameters

Session encryption key. Can be generated with docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

[mbellitti]

Right, that means I first run docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey, which generates some string base64... and I then add as an environment variable APP_KEY=base64...?

Shouldn't this step be done automatically by the install script?

[thespad]

It's generally unwise for us to invisibly generate keys used for encryption or other security purposes because users are then unaware of them.

We also try and avoid manipulating text files because it gets increasingly difficult to modify things over time.

Bookstack is one of our oldest images so did a lot of things in undesirable ways; we've made an effort to go back and modernise these old images to bring them in line with how we build new images, but doing it without breaking existing installs for users involves some compromises.

[mbellitti]

That makes sense, thank you. It might be helpful to add a more explicit warning about this to the README, the only explanation about APP_KEY is that it's a "Session encryption key, can be generated with ..." so it's hard to understand that generating it is a necessary step not handled by docker compose, especially if it was in the past.

[thespad]

Unless otherwise specified (such as QUEUE_CONNECTION= #optional) everything we list in the readme is a required setting.

Leaving settings blank will usually result in an error either from the application itself, or that we generate in the container logs if it wouldn't otherwise be obvious what was missing.

[merrime-n]

Thanks for clarification. But as long as people encounter issues, it's considered buggy; even if it is just inadequate documentation.

[thespad]

People not reading, or misunderstanding, documentation is not a bug and we're not going to redefine terms.

I will see if I can find a way to reword things to make it unambiguous that you're supposed to provide values for all the settings we say you need to provide values for.