[Docker] Permission denied on manual backups when mounting persistent backup volume

[Maystero14]

When deploying Part-DB via Docker and using the web interface to trigger a backup, an alert appears stating that var/backups/ is not a persistent volume. Following the documentation/alert suggestion, when I try to mount a persistent volume for backups, the backup process fails completely with a Permission denied error.

To Reproduce

Add a persistent volume for backups in docker-compose.yml mapped to the default internal path:
YAML

    volumes:
      - uploads:/var/www/html/uploads
      - public_media:/var/www/html/public/media
      - db:/var/www/html/var/db
      - backups:/var/www/html/var/backups

Recreate the containers
Log into the Part-DB Web UI and trigger a Full Backup.
The system throws a critical console error during the partdb:backup command execution.

Error Log

Backup failed: Create backup failed: 
[2026-06-15T07:36:34.690097+00:00] console.CRITICAL: Error thrown while running command "partdb:backup --full --overwrite '/var/www/html/var/backups/manual-v2.12.2-2026-06-15-093633.zip'". 
Message: "fopen(/var/www/html/var/backups/manual-v2.12.2-2026-06-15-093633.zip.temp6a2fab82a7840): Failed to open stream: Permission denied" 
{"exception":"[object] (PhpZip\\Exception\\InvalidArgumentException(code: 2): fopen(/var/www/html/var/backups/manual-v2.12.2-2026-06-15-093633.zip.temp6a2fab82a7840): Failed to open stream: Permission denied at /var/www/html/vendor/nelexa/zip/src/ZipFile.php:1488)"}

Expected behavior
The backup directory should have the correct default permissions assigned to the www-data user inside the container image so that persistent volume mapping via Docker Compose works seamlessly out of the box without changing permissions on the host system.

Questions regarding configuration:
What is the officially recommended way to persistent-map the var/backups directory in docker-compose.yml to prevent this warning and avoid Permission denied issues?

Should it be mapped as - backups:/var/www/html/var/backups?

Or should it be mapped outside the web server root, like - backups:/var/backups?

Desktop / Server Environment:

Part-DB Version: v2.12.2

Deployment: Docker Compose

Base OS: Linux / QNAP NAS Container Station

[mMuck]

I stumbled upon the same /var/backups what is given in the docs and the settings page. I misinterpreted this as the full path. This is a folder within the www folder. So /var/www/html/var/backups is correct.

Have you tried a docker bind mount to a local folder of the host system?

    volumes:
      - ...
      - /home/xy/backups/partdb/backups:/var/www/html/var/backups

Perhaps you have to chmod/chown this folder to your needs (www-data user)

[Maystero14]

Thank you for the suggestion! However, using a bind mount or modifying container permissions manually (via chown/chmod) is highly discouraged on QNAP NAS systems.

QNAP's Container Station uses a heavily customized and locked-down Linux kernel architecture to ensure system security. Forcing custom permissions or using direct bind mounts from the host frequently causes conflicts with QNAP’s internal storage management layer, which can lead to stability issues or even corruption of the Container Station environment itself.

The only safe, production-grade way to run containers on these platforms is to rely strictly on standard Docker Named Volumes, where the container image itself manages internal directory permissions natively from birth.

Since var/backups is a crucial directory for keeping the installation safe, would it be possible to adjust the official Part-DB Dockerfile or initialization script?

Ideally, the container startup script could ensure that the var/backups directory is automatically pre-configured with the correct www-data:www-data ownership. This would allow users on strict NAS platforms (like QNAP) to simply mount a standard - backups:/var/www/html/var/backups named volume out of the box, without encountering "Permission denied" errors or risking host system instability.

Thank you so much for your amazing work on Part-DB and for considering this improvement for NAS deployments!

[Maystero14]

Update: I have found the root cause of this issue and a potential solution.

The Root Cause. The var/backups directory does not exist in the Docker image by default; it is created dynamically by the Symfony application only when a user triggers a backup via the Web GUI.

When a user tries to mount a standard named volume to a non-existent internal path (like - backups:/var/www/html/var/backups), Docker automatically pre-creates that directory on the host system before launching the container. On specific platforms like QNAP NAS (Container Station), Docker forces root:root ownership on this newly created directory.

Later, when the application attempts to write the .zip file, the www-data user hits a Permission denied error because it cannot write into a root-owned folder.

To solve this for all NAS and strict Docker environments, the var/backups directory should be pre-created inside the Docker image during the build process and assigned the correct permissions.

You can add these lines to the official Dockerfile where other directory permissions are being set:

RUN mkdir -p /var/www/html/var/backups \
    && chown -R www-data:www-data /var/www/html/var/backups \
    && chmod -R 775 /var/www/html/var/backups