portioner/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).
• 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.