Please update the documentation DB_PASS -> DB_PASSWORD, etc

[BloodyIron]

So I'm not building the image from a docker-compose, I'm using a k8s yaml manifest deployment, and pulling the image from here : https://hub.docker.com/r/linuxserver/bookstack

The thing is the documentation says the environment variables to use are:

1. DB_USER
2. DB_PASS

Which are factually incorrect.

My pod would never successfully connect to the database until I changed the declared environment variables to:

1. DB_USERNAME
2. DB_PASSWORD

Considering that I am nowhere near the first person to have this issue, it stands to reason the documentation is leading users astray, and should be updated to the actually correct information. Can we please have this corrected?

[github-actions]

Thanks for opening your first issue here! Be sure to follow the bug or feature issue templates!

[ssddanbrown]

Which are factually incorrect.

It's not factually incorrect, It's a little more nuanced than that. I commonly use those variables fine in docker-compose set-ups.
See my comment here for an explanation into this.

[BloodyIron]

But I'm not using docker-compose at all, and the docker image does not successfully connect with the variables used as documented. It is factually incorrectly declared. Where exactly did you get the impression I'm using docker-compose? And even still, I had to go digging through a lot of other threads that this issue say they experienced to even find that changing the variables (as I described) was the solution.

This is a shortcoming of documentation, and I can't fathom why you think asking this change to happen is unacceptable. The variables documented don't work when pulling the image directly. This is the documented on the page for the docker images. Why would I bother doing a docker-compose if I can just pull the images directly that are already made, and follow the documentation on the page for that same image?

[j0nnymoe]

For what it's worth, those variables are converted to the correct ones during startup of the container. https://github.com/linuxserver/docker-bookstack/blob/master/root/etc/cont-init.d/50-config#L61

[BloodyIron]

Well if that's the expectation, well it's not happening. I passed Envs of DB_USER and DB_PASS and they weren't converted, and the app would not connect to the database until I set the passed Envs to DB_USERNAME and DB_PASSWORD. So either the documentation is inaccurate, or the actual automation of that isn't working as intended.

It's not like I didn't actually try here folks, and I'm nowhere near the first person to experience this issue. Not only do I see this issue come up in the "closed" section of issues on this repo, but I found multiple forum discussions elsewhere where people said change the Envs to the longer form and it worked for them.

So... what's more important, telling me I'm wrong, or investigating that there's something not quite right here? I'd appreciate the "invalid" label being removed, instead of assuming by default I'm just wrong (when, I'm not).

[Roxedus]

This is marked as invalid as it does not use the issue template.

[BloodyIron]

@Roxedus okay well I hear that. But I don't think this necessarily classifies as either a bug, nor a feature request. So I don't really see those templates being applicable here. Which would you prefer I use?

[ssddanbrown]

@BloodyIron

Where exactly did you get the impression I'm using docker-compose?

I didn't, I was just giving context to the environment I use those variables within, though their functionality should remain the same for whatever method you use to run the container.

... and I can't fathom why you think asking this change to happen is unacceptable.

No one has stated that.

The variables documented don't work when pulling the image directly.

They do, I just gave this a test to double check it.

As described in my comment linked previously, the scenario is a little nuanced. There can be scenarios where the variables won't take affect (Where a .env file exists with non-default DB values, often after first run).
Using the full DB_PASSWORD variable works since it overrides those in the .env file.
I'm not stating the current method of things is ideal, or that it could not be improved, but just trying to provide insight here.

[BloodyIron]

Okay so I think I'm getting unreasonably frustrated on this situation, and I want to apologise to all in this thread. My frustration comes from a simple "fix" where the documentation seems to not meet "reality"/"expectation". I'm sure I'm coming across as abrasive, and I'm sorry, I should "be better".

Now, to add some detail, and let's get a few things out of the way:

1. I'm not using docker-compose (so that this is now explicit, and not implied)
2. I'm using YAML manifest with "kind: deployment" into kubernetes, pulling the latest image from the linuxserver docker image repo (thanks for running that btw!)
3. I am not passing an .env file, what I am doing is passing Environment Variables under "env:" as a subset of "containers:": in the YAML manifest.
4. When I passed DB_USER and DB_PASS, it never worked, but the moment I changed it to DB_USERNAME and DB_PASSWORD, it "worked". "not working" as in "access denied" when trying to connect to the database, "working" as in the application connects to the database, actually provisions the database, and works "as intended" (so it seems).

Now, I don't know the justification for the use of DB_USER and DB_PASS for the docker-compose, or the documentation page on the docker image repo, but for me, those look to be the only variables that are communicated as what "should be used" so to say when using this docker image. And I think that updating the documentation to improve this communication would be beneficial to reduce future mistakes/tickets/issues/errors from whomever wants to just use the image in similar way to what I have been doing.

Perhaps that could involve a section talking about "YAML manifest for k8s" in addition to the "docker-compose" and then clarifies the DB_USERNAME and DB_PASSWORD distinction. But perhaps that is up to the decision of the linuxserver folks.

My original intent was to try and promote change so that the documentation, in whatever way, would be improved to avoid future confusion. I'd like to think that would be helpful to many, and reasonable. So at this point, are there any aspects for me to clarify? Are there disagreements about whether this is reasonable or not? Or...?

[daufinsyd]

I have the same error (tho using docker file).

Renaming to DB_USERNAME and DB_PASSWORD solved the issue.

Too bad to lose so much time figuring out what the problem is, whereas renaming the var in the doc would have made it just work.

Edit: I'm not using k8s

[leozulfiu]

Just had the same issue and changed to DB_USERNAME and DB_PASSWORD in my docker-compose.yml file and it worked. With the old env variables I just got a white page i.e. a 500 error.
Below is the error I got in log/nginx/error.log:

2022/09/11 10:48:09 [error] 265#265: *1 FastCGI sent in stderr: "PHP message: PHP Fatal error:  Uncaught PDOException: SQLSTATE[HY000] [1045] Access denied for user 'bookstack'@'bookstack.bookstack_default' (using password: YES) in /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php:70
Stack trace:
#0 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php(70): PDO->__construct()
#1 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php(46): Illuminate\Database\Connectors\Connector->createPdoConnection()
#2 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/MySqlConnector.php(24): Illuminate\Database\Connectors\Connector->createConnection()
#3 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/ConnectionFactory.php(184): Illuminate\Database\Connectors\MySqlConnector->connect()
#4 [internal function]: Illuminate\Database\Connectors\ConnectionFactory->Illuminate\Database\Connectors\{closure}()
#5 /app/www/vendor/laravel/framework/src/Illuminat...PHP message: PHP Fatal error:  Uncaught PDOException: SQLSTATE[HY000] [1045] Access denied for user 'bookstack'@'bookstack.bookstack_default' (using password: YES) in /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php:70
Stack trace:
#0 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php(70): PDO->__construct()
#1 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/Connector.php(46): Illuminate\Database\Connectors\Connector->createPdoConnection()
#2 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/MySqlConnector.php(24): Illuminate\Database\Connectors\Connector->createConnection()
#3 /app/www/vendor/laravel/framework/src/Illuminate/Database/Connectors/ConnectionFactory.php(184): Illuminate\Database\Connectors\MySqlConnector->connect()
#4 [internal function]: Illuminate\Database\Connectors\ConnectionFactory->Illuminate\Database\Connectors\{closure}()
#5 /a

And this is my (fixed) docker-compose.yml file:

version: "2"
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=http://192.168.1.19:6875
      - DB_HOST=bookstack_db
      - DB_USERNAME=bookstack
      - DB_PASSWORD=asdfasdf
      - DB_DATABASE=bookstackapp
    volumes:
      - /home/asdf/bookstack/config:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db
  bookstack_db:
    image: lscr.io/linuxserver/mariadb
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=asdfasdf
      - TZ=Europe/London
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=asdfasdf
    volumes:
      - /home/asdf/bookstack/config:/config
    restart: unless-stopped

I'm using this exact image:

REPOSITORY                      TAG                  IMAGE ID       CREATED         SIZE
lscr.io/linuxserver/bookstack   latest               27e1bce57a31   2 days ago      255MB

[riccardospeggiorin-centropaghe]

Same problems here.
The container cannot connect to the database until I change the variables name!
thanks!

[oulmanc]

As others are reporting, I had the same issue using docker compose with the database not connecting until I changed the variables to DB_USERNAME and DB_PASSWORD. As @BloodyIron suggested, the documentation should be updated to reflect this inaccuracy. I was getting a blank 500 error page until I updated the variables.

[aptalca]

The documentation is accurate