REQUIREMENTS.md

# 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.

## 2. File and Folder Structure
- **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)

## 3. Deployment and Setup
- **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.

## 4. Configuration
- **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.
docs: Formalize Synology NAS repo standards with REQUIREMENTS.md, maintenance instructions, and setup guides. Fix service typos and standardize filenames. 2026-02-22 12:43:12 -05:00			`# 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.`

			`## 2. File and Folder Structure`
			- 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)

			`## 3. Deployment and Setup`
			- 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).
feat: Implement intelligent dry-run logic for portracker and update standards 2026-02-22 15:01:27 -05:00			`- 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").`
docs: Formalize Synology NAS repo standards with REQUIREMENTS.md, maintenance instructions, and setup guides. Fix service typos and standardize filenames. 2026-02-22 12:43:12 -05:00			`- 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.`

			`## 4. Configuration`
			- 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.