[Feature Request] Run docker as non-root user

[matthiasdv]

Description

Problem

Trying to run the Homepage container as non-root. The directory that's mounted to config
Files are chown'ed to 1000:1000 at build-time:

homepage/Dockerfile

Line 45 in 8377174

COPY --link --chown=1000:1000 /public ./public/

Which causes init to fail when that directory on the host is not writable by 1000:1000 with this error:

❌ Failed to initialize required config: /app/config/settings.yaml
Reason: EACCES: permission denied, copyfile '/app/src/skeleton/settings.yaml' -> '/app/config/settings.yaml'
Hint: Make /app/config writable or manually place the config file.
Fixing ownership of /app/config
Warning: Could not chown /app/config; continuing anyway
/app/.next already owned by correct UID/GID or running as root, skipping chown
   ▲ Next.js 15.5.2
   - Local:        http://localhost:30054
   - Network:      http://0.0.0.0:30054

 ✓ Starting...
 ✓ Ready in 108ms
❌ Failed to initialize required config: /app/config/settings.yaml
Reason: EACCES: permission denied, copyfile '/app/src/skeleton/settings.yaml' -> '/app/config/settings.yaml'
Hint: Make /app/config writable or manually place the config file.
Fixing ownership of /app/config
Warning: Could not chown /app/config; continuing anyway
/app/.next already owned by correct UID/GID or running as root, skipping chown
   ▲ Next.js 15.5.2
   - Local:        http://localhost:30054
   - Network:      http://0.0.0.0:30054

 ✓ Starting...
 ✓ Ready in 106ms
❌ Failed to initialize required config: /app/config/settings.yaml
Reason: EACCES: permission denied, copyfile '/app/src/skeleton/settings.yaml' -> '/app/config/settings.yaml'
Hint: Make /app/config writable or manually place the config file.

Even if that directory on the host is writable by others, Homepage willl still throw some warnings:

025-10-08 15:34:04.157330+00:00Fixing ownership of /app/config
2025-10-08 15:34:04.157610+00:00Warning: Could not chown /app/config; continuing anyway
2025-10-08 15:34:04.158308+00:00Fixing ownership of /app/config/logs
2025-10-08 15:34:04.158543+00:00Warning: Could not chown /app/config/logs
2025-10-08 15:34:04.158953+00:00/app/.next already owned by correct UID/GID or running as root, skipping chown

So even if I run the container as non-root, init will still not be able to chown anything. It would be nice to isolate this container from host root.

Related to: truenas/apps#3345

Other

No response

[buffaloexpatbill]

Did you review https://gethomepage.dev/installation/docker/
"Running as non-root" ?

[kunklerphilip]

Homepage can currently only be run as root or with the user id 1000. Not any arbitrary user.
I'm currently having the same issue.
My apps user I use for all my containers has the user id of 568.

With a compose file like this:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config # Make sure your local config directory exists
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts
      PUID: 568
      PGID: 568

And the "/path/to/config/" directory on the host being owned by 568 and permissions drwxr-xr-x

I still get errors like @matthiasdv . The container just crashes and constantly restarts.

 ✓ Starting...
 ✓ Ready in 251ms
❌ Failed to initialize required config: /app/config/settings.yaml
Reason: EPERM: operation not permitted, copyfile '/app/src/skeleton/settings.yaml' -> '/app/config/settings.yaml'
Hint: Make /app/config writable or manually place the config file.
/app/config already owned by correct UID/GID, skipping chown
/app/.next already owned by correct UID/GID or running as root, skipping chown
   ▲ Next.js 15.5.2
   - Local:        http://localhost:3000
   - Network:      http://0.0.0.0:3000

This thread also seems to be related.

[shamoon]

If you'd like to test out the docker image tagged feature-uid and let me know how it goes

Edit: No reply, cool. Merged and released anyway. We'll see

[shamoon]

Maybe you have it mounted ro or something, but node is telling us it cant write to the dir. Inside the running container as UID 568, try touch /app/config/testfile. If that fails, the volume isn’t actually writable to the app user (even if it looks right on the host)

[kunklerphilip]

Creating the file works.
Just so there are no misunderstandings though: I am using a docker bind mount. Not a docker volume.
Portainer also shows the "next-server" is being run as user 568 in the container.

When execing into the container as user 568:

/app $ whoami
whoami: unknown uid 568
/app $ ls
config                  next-i18next.config.js  node_modules            package.json            public                  server.js               src
/app $ touch /app/config/testfile
/app $ cd /app/config/
/app/config $ ls -l
total 38
-rw-r--r--    1 568      568           1076 Nov 20 17:21 bookmarks.yaml
-rw-rw-r--    1 568      568              0 Nov 11 17:27 custom.css
-rw-rw-r--    1 568      568              0 Nov 11 17:27 custom.js
-rw-r--r--    1 568      568            196 Nov 20 17:17 docker.yaml
-rw-rw-r--    1 568      568             31 Nov 20 17:16 kubernetes.yaml
drwxrwx---    2 568      568              3 Nov 20 17:46 logs
-rw-r--r--    1 568      568            104 Nov 20 17:17 proxmox.yaml
-rw-r--r--    1 568      568           5636 Nov 20 17:19 services.yaml
-rw-r--r--    1 568      568            699 Nov 20 17:19 settings.yaml
-rwxrwx---    1 568      568              0 Nov 20 21:07 testfile
-rw-r--r--    1 568      568            843 Nov 20 17:20 widgets.yaml
/app/config $ 

[shamoon]

What type of storage is /config bound to (local vs nas/SMB/NFS)?

[kunklerphilip]

I'm running all my docker stuff on a TrueNAS Scale. It's just a local folder on that TrueNAS: /mnt/nvme/apps/homepage
No SMB or NFS Share.
And that folder is owned by 568:568 with rwxrwxr-x permissions.

[shamoon]

TrueNAS will be ZFS. ACL settings can sometimes be problematic. If you can, try mounting /config from a plain local path with simple POSIX perms. I cant reproduce this.

Inside the container as UID 568, run: node -e "require('fs').copyFileSync('/app/src/skeleton/settings.yaml','/app/config/testcopy.yaml')". If that throws EPERM, it’s the filesystem’s response, not homepage

[github-actions[bot]]

This discussion has been automatically closed because it was marked as answered. See our contributing guidelines for more details.