Difference between PGID/PUID and GID/UID when setting up docker containers

english
#1

I'm new to Docker and I've seen that some scrips for running containerized software require to specify either of those to match certain user and group. So I was wondering what is the difference between both? Examples below to illustrate.

Jellyfin uses UID/GID pair:

docker run -d \
    --name="Jellyfin" \
    --restart=always \
    --network=host \
    -p 8096:8096 \
    -e UID=1000 \
    -e GID=1000 \
    -v /media:/media \
    -v $HOME/docker/jellyfin/config:/config \
    jellyfin/jellyfin:latest

While Calibre-web uses PUID/PGID set:

docker create --name=calibre-web --restart=always \
    -v ~/books:/books \
    -v /etc/localtime:/etc/localtime:ro \
    -e PGID=1000 -e PUID=1000 \
    -p 8081:8083 \
    technosoft2000/calibre-web

While looking for info I even saw some random github repos that changed from the former to the later at some point; what's the difference between both options?

#2

I understood your question to be: "Why are these variables called PUID and PGID instead of UID and GID"? In fact they could be named anything at all. Neither Docker nor Linux care. It's the application that decides what to do with them.

Further searching revealed that this is merely a convention, and some applications do their own thing. For instance, one application uses the environment variables MAYAN_USER_UID and MAYAN_USER_GID respectively.

#3

The parameter -e sets environment variables. googling for environment variable PUID yields among others this result:

Understanding PUID and PGID on linuxserver.io, who provide a docker image for calibre-web.

Quote from that page:

Using the PUID and PGID allows our containers to map the container's internal user to a user on the host machine. All of our containers use this method of user mapping and should be applied accordingly.

Another note from that page:

We are aware that recent versions of the Docker engine have introduced the --user flag. Our images are not yet compatible with this, so we recommend continuing usage of PUID and PGID.

So, it's needed to run the container. How this is implemented is up to the maintainers of those images.

#4

I understood your question to be: “Why are these variables called PUID and PGID instead of UID and GID”? In fact they could be named anything at all. Neither Docker nor Linux care. It’s the application that decides what to do with them.

#5

This seems like a question for the developers of those applications.

#6

@MichaelHampton I don’t think so; I think there must be some specification or documentation about this somewhere, if it isn’t a Docker thing maybe is a Linux thing, but I couldn’t find it. Of course I could ask the developers, but since this question would not really be related to the development of their software, I would rather not annoy them with my tangential ignorance if possible. But maybe this is a question best suited for Superuser instead?

#7

@MichaelHampton Indeed, you were correct from the start. It seems my confusion came from me not knowing that environment variables could be called anything. Please feel free to add your response as an answer so I can mark it as solution. Also, thank you for helping out!