Synology NAS Docker Service Requirements

This document outlines the mandatory standards for services managed in this repository via Portainer.

1. User Management

Dedicated User: Every service must have a dedicated local user created on the Synology DSM.
Non-Root Execution: Containers must run under the service-specific PUID and PGID whenever possible.
Root Exception: Only services that strictly require root privileges (e.g., Traefik, Cloudflared in some network modes) are allowed to run as root.

Base Path: /volume1/docker/
Service Data: All configuration, database, and system-related files must reside in /volume1/docker/<service_name>.
User Data (Large): Large user-managed files (e.g., ebooks, movies, paperless documents) must reside in /volume1/media/<type>/.
Hierarchy Example:
- /volume1/docker/calibre/ (Config, DB)
- /volume1/media/ebooks/ (EPUB/PDF files)

Idempotent Scripts: Every service must include a create_<service>_folders.sh script.
Setup Documentation: Every service folder must contain a SETUP.md file documenting the end-to-end flow, highlighting manual pre-setup steps (user creation, ID lookup).
Intelligent Dry-Run Mode: Scripts must support a dry-run mode (default) that compares current system state with target state:
- If a folder exists, report it as "existing" with the phrase "no changes will be made".
- If owner/permissions already match, report as "matched" with current state and the phrase "no changes will be made".
- If a target folder does not exist yet during a dry-run check, report ownership/permissions as "WILL SET upon creation".
- Recursion: For recursive operations (chown -R, chmod -R), dry-run must verify all nested items and report if any deviate from the target state.
- Execute Instructions: The dry-run output must clearly instruct the user how to apply the changes (e.g., "To apply changes, run: sudo bash $0 --run").
Script Requirements:
- Must use mkdir -p to handle existing directories.
- Must set correct ownership (chown) and permissions (chmod) based on the service user.
- Must be safe to run multiple times without causing errors or data loss.
Stack Grouping: It is encouraged to group related containers (e.g., App, DB, Redis) into a single Portainer stack file.

Environment Variables: Use stack.env or Portainer environment variables for sensitive data.
Parametrization: Ideally, use ${PUID}, ${PGID}, and ${TZ} variables to maintain portability across different user accounts.