30 lines
1.9 KiB
Markdown
30 lines
1.9 KiB
Markdown
|
# 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.
|