Cache directory not persisted: HOME=/root in container vs. /home/borg/.cache/borg in compose example

[roelbeun]

Summary

The container ships with HOME=/root, so borg's default cache location is /root/.cache/borg/. However, the documented compose example mounts the cache volume at /home/borg/.cache/borg, which borg never touches. As a result, the
borg files-cache and chunks-cache live in the container's writable layer and are lost on every container recreate (image update, compose down && up, etc.).

This is a silent performance regression: backups still succeed, but every container recreate forces borg to re-read and re-hash all source data from scratch. For large repositories this changes incremental runs from minutes to many hours/days.

Environment

• borg-ui: 2.1.0
• borg: 1.4.4
• borg2: 2.0.0b21
• Image: ainullcode/borg-ui:latest
• Deployment: docker-compose, single host

Evidence

Inside the running container:

$ docker exec borg-web-ui sh -c 'env | grep -iE "borg|home"'
HOME=/root
BORG1_VERSION=1.4.4
BORG2_VERSION=2.0.0b21
BORG_BACKUP_PATH=/backups
...

The bind-mounted directory at /home/borg/.cache/borg/ contains 10 repo cache directories, but the file mtimes inside them are months old:

-rw------- 1 root root 96336214 Apr  5 02:09 chunks
-rw------- 1 root root      597 Apr  5 02:09 config
-rw------- 1 root root 56380200 Apr  5 02:09 files
-rw------- 1 root root        2 Apr  9 14:48 pre12-meta

Meanwhile recent backup runs (verified via /api/activity/backup/{id}/logs/download) complete successfully with rc 0, which means borg is reading/writing a working cache somewhere — just not in the bind-mounted path. The only writable location that fits is /root/.cache/borg/ in the container's ephemeral layer.

No BORG_CACHE_DIR or BORG_BASE_DIR is set in the container environment, so borg falls back to $HOME/.cache/borg/, which resolves to /root/.cache/borg/.

The compose example in the README documents the mount as /home/borg/.cache/borg, which is inconsistent with the image's actual HOME.

Impact

On my setup, a ~10 TB media repository takes 33–51 hours for what should be a quick incremental run, because borg re-reads every source file across the network to rebuild the chunk index. With a persisted files-cache, the same run would complete in minutes (only newly added/changed files need to be hashed).

This is easy to miss because:

• Backups still succeed; nothing fails loudly.
• The directory at /home/borg/.cache/borg/ is non-empty (it was populated before the HOME change took effect), so a casual check looks fine.
• The UI doesn't surface cache state.

Proposed fix

Either of the following would resolve the mismatch. I'd lean toward option 1 because it doesn't risk breaking other HOME-dependent paths in the image:

1. Update the compose example (and any other docs) to mount the cache at
   /root/.cache/borg:

   volumes:
     - ./cache:/root/.cache/borg
   

2. Change the image's HOME to /home/borg (the directory already exists inside the image with the expected .cache/borg/ layout), and keep the compose example as is.

3. Set BORG_CACHE_DIR in the image to a stable path inside one of the persisted volumes (e.g. /data/borg-cache/), and document that path. This has the bonus of decoupling the cache location from HOME entirely.

Question

Is the current HOME=/root intentional, or a side-effect of switching base images? Knowing the intent would help decide between fix 1 and fix 2.

[roelbeun]

Let me know if i need to promote this discussion to an issue

[roelbeun]

@karanhudia ℹ️

[karanhudia]

Thanks for bringing this up @roelbeun. Your research looks solid 💪

Let me take a look at this and I will keep you posted in this thread.

[karanhudia]

Thanks again for the detailed write-up @roelbeun. I dug through this and there is one important nuance: docker exec without -u borg shows the root exec environment, while the app process normally runs as borg with HOME=/home/borg.

That said, I did find a real cache persistence bug in the same area: a fresh named volume mounted at /home/borg/.cache/borg can be created as root:root, so the borg runtime user cannot write the files/chunks cache there. That makes the documented cache volume ineffective for the default setup.

I opened a fix in #565. It sets BORG_CACHE_DIR=/home/borg/.cache/borg explicitly, pre-creates the path in the runtime base, and has the entrypoint repair ownership/permissions on startup so existing root-owned cache volumes are fixed too.

[roelbeun]

sounds good thanks, for my setup ive added the volume ./cache:/root/.cache/borg as my environment variable says HOME=/root. That should not impact any future changes I think? Please confirm. Ill mark the discussion closed

[karanhudia]

@roelbeun confirmed. The cache fix is included in the latest release, v2.2.1.

Your ./cache:/root/.cache/borg mount should not break future changes, but with v2.2.1 it is not the default cache path Borg UI uses unless you explicitly set BORG_CACHE_DIR=/root/.cache/borg. The image now pins Borg's active cache to BORG_CACHE_DIR=/home/borg/.cache/borg and repairs ownership on startup, so for the default setup use:

- ./cache:/home/borg/.cache/borg

or the named cache volume from the compose example. Then the cache is persisted at the path the app is actually using. Closing the discussion is fine, and thanks again for the detailed report.

[roelbeun]

@karanhudia just a final comment, I don't see the BORG_CACHE_DIR environment by default in the docker compose file in v2.2.1.

Can I just add it myself for now or do we want to change the docker template. I want to avoid breaking the cache dir once I upgrade to v2.2.1

[karanhudia]

You can add it directly. Its already documented as well.