What's Going Wrong?

Docker container fails to create directories on mounted volumes due to UID mismatch between container user and host volume ownership.

When running Hermes in Docker on UnRAID, volume mounts fail with Permission denied errors:

mkdir: cannot create directory '/opt/data/cron': Permission denied
mkdir: cannot create directory '/opt/data/sessions': Permission denied
mkdir: cannot create directory '/opt/data/logs': Permission denied

The entrypoint never runs usermod or chown because the container starts as the hermes user (UID 10000), not root. The entrypoint relies on if [ "$(id -u)" = "0" ] to trigger permission fixes, but this block is bypassed when the container starts as non-root.

Steps Taken

1. Pulled Hermes Docker image
2. Configured environment variables:
   • HERMES_UID=99
   • HERMES_GID=100
   • HERMES_HOME=/opt/data
3. Mounted host volume: /mnt/user/appdata/hermes-agent:/opt/data
4. Container starts but cannot write to mounted volume

Debugging findings:

# Container starts with hardcoded UID (not root)
docker inspect hermes-agent | jq '.[0].Config.User'
# → "hermes"

# Hermes runs as UID 10000, volume owned by UID 99
docker exec hermes-agent id
# → uid=10000(hermes) gid=10000(hermes)

# Entrypoint never triggers usermod/chown
docker logs hermes-agent | grep -E "(Changing|usermod|hermes UID)"
# → (empty, block skipped because id -u != 0)

Root cause: The Dockerfile ends with USER hermes, which causes Docker to start the container as UID 10000. The entrypoint's permission-fixing logic (if [ "$(id -u)" = "0" ]) is bypassed entirely.

Installation Method

Docker

Operating System

Slackware (UnraidOS 7.2.4)

What I've Already Tried

Solution A: Runtime flag (current workaround)

In UnRAID "Extra Parameters", adding --user 0:0 forces the container to start as root, allowing the entrypoint to run usermod and chown:

docker logs hermes-agent | grep -E "(Changing|Dropping)"
# → Changing hermes UID to 99
# → Changing hermes GID to 100
# → Dropping root privileges

This works but is undocumented and non-obvious.

Proposed Fix (optional)

1. Documentation: Add a "Docker on UnRAID" section to the Docker docs explaining the --user 0:0 requirement or the need to set HERMES_UID/HERMES_GID to match the host volume owner.

2. Alternative: Move USER hermes from the Dockerfile to after ENTRYPOINT, so the entrypoint always executes as root first:

   # Current (problematic):
   USER hermes
   ENTRYPOINT ["bash", "/opt/hermes/docker/entrypoint.sh"]
   
   # Alternative:
   ENTRYPOINT ["bash", "/opt/hermes/docker/entrypoint.sh"]
   # (hermes user change happens inside entrypoint via gosu)

3. Fallback error: Add early detection in entrypoint if $HERMES_HOME is not writable, with a clear error message directing users to the documentation.