Struggling with ‘Permission Denied’ errors in your Dockerized UrBackup setup? This guide breaks down the common UID/GID permission pitfalls between containers and hosts, providing three practical solutions from quick fixes to best-practice configurations.

From the Trenches: Why Your Docker UrBackup Can’t Write to Its Volumes (And How to Fix It)

It was 2 AM. A P1 alert screamed from PagerDuty: ‘CRITICAL: Backup Lag > 24h on prod-db-01’. My heart sank. We’d just migrated our backup server to a new VM host. The docker-compose up -d had worked flawlessly, the UI was up, but silently, for hours, every single backup job was failing with a cryptic ‘cannot create file’ error. It took me another hour of tired debugging to realize the problem wasn’t in the app, but in a simple, fundamental Linux concept: user identity. A classic case of the container’s user being a complete stranger to the host’s filesystem. And trust me, I see this exact issue pop up constantly, just like in that Reddit thread about UrBackup.

The Root Cause: A Case of Mistaken Identity

So, what’s really going on here? It’s not magic, and it’s not Docker being difficult. It’s all about how Linux handles file permissions. Linux doesn’t care about usernames like ‘darian’ or ‘urbackup’. It only cares about numeric IDs: a User ID (UID) and a Group ID (GID).

Here’s the problem:

• Inside your UrBackup container, the application is running as a specific user, let’s say ‘urbackup’, which has a specific UID and GID (e.g., UID=101, GID=102).
• On your host machine, you create a directory like /srv/urbackup/data. This directory is owned by the user who created it, maybe your own user account (e.g., UID=1000, GID=1000) or root (UID=0, GID=0).
• When you map this directory as a volume (-v /srv/urbackup/data:/backups), the container’s user (UID 101) tries to write to a directory owned by the host’s user (UID 1000).

Linux sees this and says, “Nope. You’re not the owner. Access denied.” The usernames don’t matter; the numbers don’t match. That’s it. That’s the entire problem.

The Solutions: From Hasty to Pro

Alright, enough theory. Let’s get this fixed so you can get back to what matters. I’ve got three ways to tackle this, from the “get it working now” approach to the one you’ll thank yourself for later.

1. The Quick & Dirty Fix: The ‘chmod 777’ Hammer

This is the first thing everyone tries. You find the directory on your host that you mapped into the container and you give everyone and their dog full read, write, and execute permissions.

sudo chmod -R 777 /srv/urbackup/data

Does it work? Yes. Should you use it? Almost never.

A Word From The Trenches: Please, do not use chmod 777 on anything that matters. It’s a massive security hole. You’re telling the OS that any user, any process, any script on that machine can read, modify, and delete your precious backups. It’s fine for a quick test on your laptop to confirm a theory, but it has no place in a real environment. We call this an ‘anti-pattern’ for a reason.

2. The Proper Fix: Match the Container’s Identity

The correct way to solve this is to make the host directory’s owner match the container’s user. We’ll find out what the container’s user ID is, and then apply it to the host directory.

Step 1: Find the UID/GID inside the container.

First, get your container running. Then, use docker exec to run the id command inside it. You’ll need to know the name of the user the application runs as, which is usually in the image documentation (for UrBackup, it’s often ‘urbackup’).

# Replace 'urbackup_container_name' with your actual container name
docker exec -it urbackup_container_name id urbackup

# The output will look something like this:
# uid=101(urbackup) gid=102(urbackup) groups=102(urbackup)

There’s our answer. The container needs its files to be owned by UID 101 and GID 102.

Step 2: Change the owner on the host directory.

Now, go back to your host machine’s terminal and use chown to recursively change the ownership of your data directory to match those numbers.

# Use the UID and GID you found in the previous step
sudo chown -R 101:102 /srv/urbackup/data

Restart your container, and it should now have the permissions it needs to write to the volume. This is secure, specific, and the right way to handle it manually.

3. The ‘Docker-Native’ Fix: Using PUID & PGID

This is my preferred method and, in my opinion, the most robust and portable. Many modern Docker images, especially those from popular communities like linuxserver.io, are built to solve this problem elegantly. They let you tell the container which UID and GID to run as, using environment variables.

Step 1: Find the UID/GID of the desired user on your HOST.

Decide which user on your host machine should own the backup files. This is often your own user account. Run the id command on the host, not in the container.

# Run this on your docker host terminal
id

# Output might be:
# uid=1000(darian) gid=1000(darian) groups=1000(darian),27(sudo)

So, my PUID (User ID) is 1000 and my PGID (Group ID) is 1000.

Step 2: Pass these values to the container.

Now, you just add these values as environment variables to your docker-compose.yml file. The container’s startup script will handle the rest, ensuring its internal user matches these IDs.

version: "3.7"
services:
  urbackup:
    image: urbackup/urbackup-server:latest
    container_name: urbackup
    restart: unless-stopped
    environment:
      - PUID=1000  # <-- The UID from your host user
      - PGID=1000  # <-- The GID from your host user
      - TZ=America/New_York
    volumes:
      - /srv/urbackup/database:/var/urbackup
      - /srv/urbackup/backups:/backups
    ports:
      - "55413-55415:55413-55415"
      - "35623:35623/udp"

Pro Tip: Not all images support the PUID/PGID variables. Always check the documentation for the specific Docker image you’re using on Docker Hub. If they don’t support it, fall back to Method #2.

Comparing The Solutions

Method	Pros	Cons
1. The chmod 777 Hammer	Fastest way to see if permissions are the issue.	Extremely insecure. Hides the real problem. Not a real solution.
2. Manual chown	Secure and correct. Teaches the underlying principle.	Requires manual steps (exec, chown). Can be tedious.
3. PUID/PGID Variables	Declarative, portable, and secure. Best practice. Set it once in your compose file and forget it.	Requires the Docker image to support it.

At the end of the day, that ‘permission denied’ error is a frustrating but valuable lesson. It forces us to remember that containers aren’t magic VMs; they are just isolated processes running on a shared Linux kernel. Understanding how the container’s identity interacts with the host’s filesystem is a fundamental skill. Take the time to use method 2 or 3—your future self will thank you when it’s not 2 AM and things just work.

---

🤖 Frequently Asked Questions