project-charlie/tsg/permissions.md

Permissions troubleshooting

PRM0001

Description

A container runs as a non-root UID/GID, but its bind-mounted runtime data directory is owned by another host identity. The service may start and read the mount, but writes fail when it creates state, cache, database, lock, or snapshot files.

Use /charlie-stack-gitea to find the stack repo and runtime paths, then /charlie-grafana-logs to confirm the log signature.

Symptoms

• Repeated permission denied write failures in container logs.
• Application-specific save, cache, database, lock, or snapshot errors.
• The mounted host path is present, but ownership does not match the compose service user.

For nitter-redis, Redis reported temp RDB writes failing under /data, then Background saving error.

How to confirm

Check the stack inventory row, then inspect the stack repo README.md and docker-compose.yml for the service user, bind mount, and expected first-time host prep.

In Grafana logs, start with the stack as compose_project and narrow to the service with service_name. Count the relevant permission errors and keep a few representative lines.

On the owner host, compare the bind-mounted host path ownership and mode with the UID/GID used by the compose service.

Ways to fix

• Change ownership of the runtime data path to the UID/GID used by the service.
• If only one file is affected, change that file rather than the whole runtime directory.
• If the runtime path was created by the wrong process, recreate it with the ownership documented by the stack repo.
• Redeploy or restart the service only after the host path ownership is correct.