Homepage not starting when PUID and GUID set

[ChoosenMEME]

Description

When i set PGID and PUID the container will instantly go unhealthy, and disk is spinning until i stop the container again. This does not happen when those variables are not set, then it starts like expected, and disks stop spinning.

I also checked if permissions might be wrong, but user and group docker-user has rwx

docker-user@docker:/mnt/data$ id docker-user
uid=3001(docker-user) gid=3001(docker-user)

docker-user@docker:/mnt/data$ getfacl homepage/
# file: homepage/
# owner: docker-user
# group: docker-user
user::rwx
user:root:rwx
user:docker-user:rwx
group::rwx
group:docker-user:rwx
mask::rwx
other::rwx
default:user::rwx
default:user:root:rwx
default:user:docker-user:rwx
default:group::rwx
default:group:docker-user:rwx
default:mask::rwx
default:other::---

homepage version

0.9.2

Installation method

Docker

Configuration

docker-compose.yml

services:  
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    volumes:
      - /mnt/data/homepage:/app/config
    networks:
      - proxy
    environment:
      PUID: 3001
      PGID: 3001
      LOG_LEVEL: debug
    restart: unless-stopped
    ports:
      - 3000:3000

networks:
  proxy:
    external: true

Container Logs

There are none when started as user

if started as root:

Listening on port 3000

Browser Logs

No response

Troubleshooting

this is not relevant, as topic is not widgets

[glime-ai[bot]]

Thanks for posting a discussion about homepage here on GitHub. Homepage now uses a fancy new AI tool thanks to our friends at Glime, so the answer below is the AI bot's attempt to answer your question. If you feel it's sufficient you can mark the answer and close this post, otherwise feel free to leave it open of course!

Thanks for using Homepage! ❤️

---

Based on the information provided, it seems that setting the PUID and PGID environment variables is causing the container to become unhealthy and the disk to spin continuously. This behavior suggests that the container is attempting to perform an operation that it cannot complete, possibly related to file permissions or ownership.

The PUID and PGID are used to set the user ID and group ID for the process running inside the container. This is typically done to ensure that any files written by the container have the correct permissions when accessed from the host system. However, if the container is trying to change ownership or permissions of existing files to match these IDs and encounters a large number of files or files that it cannot modify (due to being read-only or other restrictions), it could lead to the symptoms you're experiencing.

Here are a few steps you can take to troubleshoot the issue:

1. Verify that the PUID and PGID values you are setting correspond to the docker-user on your host system. You've already done this with the id docker-user command, which is good.

2. Ensure that the volume /mnt/data/homepage is owned by the docker-user and has the correct permissions set. It seems you have already checked this with getfacl, but it's worth double-checking.

3. Check if there are any large numbers of files or subdirectories within /mnt/data/homepage that could be causing the container to take a long time to change permissions or ownership.

4. Look for any logs that might indicate what the container is doing when it becomes unhealthy. Since you mentioned there are no logs when started as a user, you might need to enable more verbose logging or attach to the container to see if there's any output to the console.

5. Review the documentation and any related issues on the official repository for the Homepage project to see if others have encountered similar problems and if there are any known solutions or workarounds.

6. As a last resort, you could try setting the PUID and PGID to 0 to run the container as root, which should have unrestricted access to all files. However, this is not recommended for security reasons and should only be done temporarily for troubleshooting purposes.

If you continue to experience issues, you may want to reach out to the maintainers of the Homepage project or file an issue on their GitHub repository with the details of your problem.

This comment was generated by Glime.

[mscheltienne]

Same issue. This configuration fails:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
    ports:
      - 30007:3000
    volumes:
      - /mnt/tank/data-apps/homepage:/app/config
    restart: unless-stopped
networks: {}

Despite the correct permissions for PUID/PGID 568.

[SheepReaper]

I'm having the same problem. If I specify PUID and PGID startup time is north of 5 minutes. makes it impossible to do a stack deploy with since the health check times out well before that and causes the container to restart. removing the variables works around the issue. This is on a debian VM on a Pi5. first thing to look at is su-exec in the entrypoint.
the root cause of my problem is that the server doesn't start listening for the whole 5 minutes, so the healthcheck to localhost:3000 is going to fail since nothing is listening yet. But running as root starts instantly. what gives?

[jerobins]

I find myself here for the same reason. The docker log says "Ready in 285ms" but it is more like 5mins + 285ms.

[Fernando-Checa]

I use this and works fine for me:

services:
    homepage:
        image: ghcr.io/gethomepage/homepage:latest
        container_name: homepage
        environment:
              - PUID=1000 # optional, your user id
              - PGID=1000 # optional, your group id
.....

[shamoon]

Not much to add here other than that this seems to only affect certain users (see above). Since it’s been like this since the PR that added rootless support it’s not something I’m currently planning to change, always open to other thoughts.

[ihatemyisp]

The original PR is quite old: #644 so I can’t exactly answer your question but if there is a way to slim that down without breaking things that would be fine. Open to suggestions, I’m not an expert on this topic, and really not keen to break something that works, at least for most.

I’ve created a docker image tagged feature-rootless-tweaks if anyone would like to test.

Thanks. If that is based off the branch of the same name then I don't even have to test it to know it's likely to solve the slow start issue. 34e3a0327f6b2b4083cffd9412737e318924da22 is what solved it for me, so adding the /app/public to the chown should be ok, speed wise.

I'll test your image as soon as I get a chance.

[ihatemyisp]

I’ve created a docker image tagged feature-rootless-tweaks if anyone would like to test.

So with just /app/config I'm looking at about 5 seconds to "healthy" from compose up. When adding /app/public it jumps to around 15ish seconds. While relatively longer, it's still immensely shorter than the minute(s) it was with just /app.

[shamoon]

Great thanks, if others can confirm that would be helpful, again, don’t want to rush into this. I might see if I can whittle it down a bit more even

[UnDifferential]

Confirming the feature-rootless-tweaks image dropped the startup time from over 5 minutes to under 10 seconds on my setup.

[ihatemyisp]

Great thanks, if others can confirm that would be helpful, again, don’t want to rush into this. I might see if I can whittle it down a bit more even

Just for context, I'm using Docker compose on a TrueNAS Scale 24.10.2 with PUID and PGID set via environment variables.

[jerobins]

Using feature-rootless-tweaks ... Oh man, that's so nice. Available immediately from compose up. I use docker-proxy and labels to configure everything across 3 servers, no issues.

…

On Tue, Mar 18, 2025 at 7:00 PM shamoon ***@***.***> wrote: Great thanks, if others can confirm that would be helpful, again, don’t want to rush into this. I might see if I can whittle it down a bit more even — Reply to this email directly, view it on GitHub <#3654 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXHHZZOQ2E3GKSNKMUU532VCQP5AVCNFSM6AAAAABJSTFSFKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENJUGQ2TGNQ> . You are receiving this because you commented.Message ID: ***@***.***>

[jerobins]

I'm on a Debian box with PUID and PGID set via environment variables: * Linux quark 5.10.0-34-amd64 #1 SMP Debian 5.10.234-1 (2025-02-24) x86_64 GNU/Linux * Docker version 28.0.1, build 068a01e Went from 5 mins to seconds.

…

On Tue, Mar 18, 2025 at 8:36 PM IhatemyISP ***@***.***> wrote: Great thanks, if others can confirm that would be helpful, again, don’t want to rush into this. I might see if I can whittle it down a bit more even Just for context, I'm using Docker compose on a TrueNAS Scale 24.10.2 with PUID and PGID set via environment variables. — Reply to this email directly, view it on GitHub <#3654 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXHH5SZBPLWU3B5CNFMNL2VC3XDAVCNFSM6AAAAABJSTFSFKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENJUGUYDAMY> . You are receiving this because you commented.Message ID: ***@***.***>

[shamoon]

Thanks for the enthusiasm everyone. This seems pretty safe to me (famous last words??)

If anyone here has more to add (or concerns or whatever) feel free

#5037

[github-actions[bot]]

This discussion has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.

[shamoon]

Hi all — quick follow-up for those who had slow startups fixed by #5037:

We’re considering a refinement to restore ownership fixups for paths like /app/.next (which some setups need for PUID/PGID to work properly), but it now only runs conditionally when ownership doesn't match — so it shouldn’t bring back the long startup times.

Would really appreciate if anyone here could test the feature-rootless-tweaks (branch feature/rootless-tweaks) image and confirm it still starts quickly on your setup.

Thanks again for all the original reports and testing — this is what makes improving homepage possible.

[jerobins]

Works great here. Noted the msg: /app/config already owned by correct UID/GID, skipping chown

[ihatemyisp]

Will test later today and let you know.

[shamoon]

Thanks again

[github-actions[bot]]

This discussion has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.