starred/audiobookshelf-advplyr

Fork 0

mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-03-02 22:46:55 -05:00

[Enhancement]: Run container as user with environmental variable #2315

New issue

Open

opened 2026-02-20 10:18:10 -05:00 by deekerman · 8 comments

deekerman commented

2026-02-20 10:18:10 -05:00

Owner

Originally created by @1alexhurts on GitHub (Oct 16, 2024).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

check for PUID GUID environmental variable on starting the container, and run as that user

Why would this be helpful?

Permissions! They're a pain and this is helpful. The linuxserver containers are beloved and this is part of why

Future Implementation (Screenshot)

I thought something like this in the dockerfile/image could work, but the container couldn't run su-exec and I couldn't figure out how to install it. I don't know what I'm doing

#!/bin/sh

if [ -n "$PUID" ] && [ -n "$PGID" ]; then
echo "Starting as UID: $PUID, GID: $PGID"

if ! getent group appgroup > /dev/null; then
    addgroup -g "$PGID" appgroup || true
fi

if ! id -u appuser > /dev/null; then
    adduser -u "$PUID" -G appgroup -D appuser || true
fi

chown -R appuser:appgroup /path/to/audiobookshelf/data

exec su-exec appuser "$@"

else
echo "Starting as root"
exec "$@"
fi

Audiobookshelf Server Version

2.15.0

Current Implementation (Screenshot)

Container details in portainer

Originally created by @1alexhurts on GitHub (Oct 16, 2024). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement check for PUID GUID environmental variable on starting the container, and run as that user ### Why would this be helpful? Permissions! They're a pain and this is helpful. The linuxserver containers are beloved and this is part of why ### Future Implementation (Screenshot) I thought something like this in the dockerfile/image could work, but the container couldn't run su-exec and I couldn't figure out how to install it. I don't know what I'm doing #!/bin/sh if [ -n "$PUID" ] && [ -n "$PGID" ]; then echo "Starting as UID: $PUID, GID: $PGID" if ! getent group appgroup > /dev/null; then addgroup -g "$PGID" appgroup || true fi if ! id -u appuser > /dev/null; then adduser -u "$PUID" -G appgroup -D appuser || true fi chown -R appuser:appgroup /path/to/audiobookshelf/data exec su-exec appuser "$@" else echo "Starting as root" exec "$@" fi ### Audiobookshelf Server Version 2.15.0 ### Current Implementation (Screenshot) Container details in portainer

deekerman added the

enhancement

backlog

labels

2026-02-20 10:18:10 -05:00

deekerman commented

2026-02-20 10:18:10 -05:00

Author

Owner

@nichwall commented on GitHub (Oct 16, 2024):

ABS does not use PUID or GUID. You should use the user directive because this is supported by docker itself instead of requiring individual containers to correctly use PUID or GUID. An example below (edited due to typo):

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./metadata:/metadata
      - ./config:/config
    # You can use the following to run the ABS
    # docker container as a specific user. You will need to change
    # the UID and GID to the correct values for your user.
    user: 1000:1000
    restart: unless-stopped

@nichwall commented on GitHub (Oct 16, 2024): ABS does not use `PUID` or `GUID`. You should use the `user` directive because this is supported by docker itself instead of requiring individual containers to correctly use `PUID` or `GUID`. An example below (edited due to typo): ``` services: audiobookshelf: image: ghcr.io/advplyr/audiobookshelf:latest ports: - 13378:80 volumes: - ./audiobooks:/audiobooks - ./podcasts:/podcasts - ./metadata:/metadata - ./config:/config # You can use the following to run the ABS # docker container as a specific user. You will need to change # the UID and GID to the correct values for your user. user: 1000:1000 restart: unless-stopped ```

deekerman commented

2026-02-20 10:18:10 -05:00

Author

Owner

@advplyr commented on GitHub (Oct 16, 2024):

I think someone mentioned that linuxserver started doing that before docker had made available user. I'm not sure if that's true but I don't see the benefit of adding environment variables when there is user built-in.

@advplyr commented on GitHub (Oct 16, 2024): I think someone mentioned that linuxserver started doing that before docker had made available `user`. I'm not sure if that's true but I don't see the benefit of adding environment variables when there is `user` built-in.

deekerman commented

2026-02-20 10:18:10 -05:00

Author

Owner

@1alexhurts commented on GitHub (Oct 18, 2024):

Some containers need to do root stuff at startup and then switch to a user,
I believe that's why. Again, I'm a beginner I may be missing something. My
reverse proxy is an example, putting it in the docker compose like your
example doesn't work, it won't start. They built in at a certain point to
switch user with a variable.

Environmental variables makes it easy and more consistent container to
container, which is the benefit of using linuxserver containers and why
I've made the request

On Wed, Oct 16, 2024 at 5:50 PM advplyr @.***> wrote:

I think someone mentioned that linuxserver started doing that before
docker had made available user. I'm not sure if that's true but I don't
see the benefit of adding environment variables when there is user
built-in.

—
Reply to this email directly, view it on GitHub
https://github.com/advplyr/audiobookshelf/issues/3527#issuecomment-2418027233,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/BCDNZWNEKOMITZLVMPR6KCTZ33NQTAVCNFSM6AAAAABQAQ226WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMJYGAZDOMRTGM
.
You are receiving this because you authored the thread.Message ID:
@.***>

@1alexhurts commented on GitHub (Oct 18, 2024): Some containers need to do root stuff at startup and then switch to a user, I believe that's why. Again, I'm a beginner I may be missing something. My reverse proxy is an example, putting it in the docker compose like your example doesn't work, it won't start. They built in at a certain point to switch user with a variable. Environmental variables makes it easy and more consistent container to container, which is the benefit of using linuxserver containers and why I've made the request On Wed, Oct 16, 2024 at 5:50 PM advplyr ***@***.***> wrote: > I think someone mentioned that linuxserver started doing that before > docker had made available user. I'm not sure if that's true but I don't > see the benefit of adding environment variables when there is user > built-in. > > — > Reply to this email directly, view it on GitHub > <https://github.com/advplyr/audiobookshelf/issues/3527#issuecomment-2418027233>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/BCDNZWNEKOMITZLVMPR6KCTZ33NQTAVCNFSM6AAAAABQAQ226WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMJYGAZDOMRTGM> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

deekerman commented

2026-02-20 10:18:11 -05:00

Author

Owner

@cw1 commented on GitHub (Dec 20, 2024):

ABS does not use PUID or GUID. You should use the user directive because this is supported by docker itself instead of requiring individual containers to correctly use PUID or GUID. An example below (edited due to typo):
services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./metadata:/metadata
      - ./config:/config
    # You can use the following to run the ABS
    # docker container as a specific user. You will need to change
    # the UID and GID to the correct values for your user.
    user: 1000:1000
    restart: unless-stopped

@nichwall : I've tested your docker-compose, but audiobookshelf doesn't start because it's missing to permission to open port 80 inside the container. You need to add the environment variable PORT and set it to an unprivileged port (>1024).

BTW: I couldn't find the PORT variable in the documentation and needed to look at index.js to find out. But that's maybe more of a documentation issue.

@cw1 commented on GitHub (Dec 20, 2024): > ABS does not use `PUID` or `GUID`. You should use the `user` directive because this is supported by docker itself instead of requiring individual containers to correctly use `PUID` or `GUID`. An example below (edited due to typo): > > ``` > services: > audiobookshelf: > image: ghcr.io/advplyr/audiobookshelf:latest > ports: > - 13378:80 > volumes: > - ./audiobooks:/audiobooks > - ./podcasts:/podcasts > - ./metadata:/metadata > - ./config:/config > # You can use the following to run the ABS > # docker container as a specific user. You will need to change > # the UID and GID to the correct values for your user. > user: 1000:1000 > restart: unless-stopped > ``` @nichwall : I've tested your docker-compose, but audiobookshelf doesn't start because it's missing to permission to open port 80 inside the container. You need to add the environment variable `PORT` and set it to an unprivileged port (>1024). BTW: I couldn't find the `PORT` variable in the documentation and needed to look at `index.js` to find out. But that's maybe more of a documentation issue.

deekerman commented

2026-02-20 10:18:11 -05:00

Author

Owner

@lhanson commented on GitHub (Jan 11, 2025):

BTW: I couldn't find the PORT variable in the documentation and needed to look at index.js to find out. But that's maybe more of a documentation issue.

Came here looking for something similar. I could not get the container to start as documented because it was trying to open port 80. The undocumented PORT variable is what I was looking for.

@lhanson commented on GitHub (Jan 11, 2025): > BTW: I couldn't find the `PORT` variable in the documentation and needed to look at `index.js` to find out. But that's maybe more of a documentation issue. Came here looking for something similar. I could not get the container to start as documented because it was trying to open port 80. The undocumented `PORT` variable is what I was looking for.

deekerman commented

2026-02-20 10:18:11 -05:00

Author

Owner

@nichwall commented on GitHub (Jan 12, 2025):

Environment variables are documented on the ABS website.

https://www.audiobookshelf.org/docs#network

@nichwall commented on GitHub (Jan 12, 2025): Environment variables are documented on the ABS website. https://www.audiobookshelf.org/docs#network

deekerman commented

2026-02-20 10:18:11 -05:00

Author

Owner

@matru commented on GitHub (Jan 26, 2025):

@lhanson @cw1 so that means port 3333 is what we can use as an alternative?

Update: So it turns out that when using the --user option, you can't really use port 80, actually you cannot use any of the privileged TCP/UDP ports below 1024. Since PORT env changes the container port, we specify something that isn't in that range of below 1024, it does not need to be 3333 and I think the developer just uses that locally? Not sure. Anyways I run it on a completely different port now, but one that is not in the range <1024, by specifying it the PORT env variable, and it works fine. Be sure to also specify the port to docker, example:

environment:
  - PORT=your_new_port # must not be a privileged port in the range of <1024.
ports:
  - your_new_port:your_new_port

@matru commented on GitHub (Jan 26, 2025): @lhanson @cw1 so that means port 3333 is what we can use as an alternative? Update: So it turns out that when using the --user option, you can't really use port 80, actually you cannot use any of the privileged TCP/UDP ports below 1024. Since `PORT` env changes the container port, we specify something that isn't in that range of below 1024, it does not need to be 3333 and I think the developer just uses that locally? Not sure. Anyways I run it on a completely different port now, but one that is not in the range <1024, by specifying it the `PORT` env variable, and it works fine. Be sure to also specify the port to docker, example: ``` environment: - PORT=your_new_port # must not be a privileged port in the range of <1024. ports: - your_new_port:your_new_port ```

deekerman commented

2026-02-20 10:18:11 -05:00

Author

Owner

@jkjustjoshing commented on GitHub (Feb 25, 2025):

Make sure that the volumes are for the correct user. I used the PORT>1024 method but the container still wouldn't start. I shut down the container, chown'd all the volume directories, and restarted the container and everything worked.

@jkjustjoshing commented on GitHub (Feb 25, 2025): Make sure that the volumes are for the correct user. I used the `PORT>1024` method but the container still wouldn't start. I shut down the container, `chown`'d all the volume directories, and restarted the container and everything worked.

deekerman referenced this issue

2026-02-20 10:19:13 -05:00

[Bug]: upload issues #2430