budget-tracker/skills/qnap-docker/SKILL.md

name, description

name	description
qnap-docker	Create and deploy Docker Compose services on Christophe's QNAP NAS. Use whenever asked to create, add, install, or deploy a Docker container/service on the QNAP. Handles volume directory creation, proper PUID/PGID permissions, LinuxServer.io image conventions, swag_lan network, and Portainer stack deployment.

QNAP Docker Skill

Environment

Parameter	Value
Volume base path	/share/ZFS24_DATA/docker/<container_name>/
PUID	1005
PGID	100
TZ	Europe/Paris
Network	swag_lan (external)
Preferred images	lscr.io/linuxserver/<app>:latest

Workflow

1. Create volume directory on QNAP

Christophe's QNAP NAS est accessible via SSH ou Portainer. Pour créer le dossier :

# Via SSH (si dispo)
ssh admin@<qnap-ip> "mkdir -p /share/ZFS24_DATA/docker/<container_name>"

# Ou via un exec dans le conteneur approprié

Si on passe par Portainer, inclure la création du dossier dans le script de déploiement ou demander à Christophe de le créer si nécessaire.

2. Compose template

services:
  <container_name>:
    image: lscr.io/linuxserver/<app>:latest
    container_name: <container_name>
    volumes:
      - /share/ZFS24_DATA/docker/<container_name>:/config
      # Ajouter d'autres volumes si besoin (ex: /share/ZFS24_DATA/docker/<container_name>/data:/data)
    environment:
      - PUID=1005
      - PGID=100
      - TZ=Europe/Paris
      # Variables spécifiques à l'app ici
    ports:
      - <host_port>:<container_port>
    restart: always

networks:
  default:
    name: swag_lan
    external: true

3. Règles importantes

• Nom du dossier = nom du container — toujours utiliser le même nom pour s'y retrouver
• Images LinuxServer (lscr.io/linuxserver/) : toujours inclure PUID=1005, PGID=100, TZ=Europe/Paris
• Images NON-LinuxServer : NE PAS ajouter PUID/PGID — adapter uniquement les variables d'env définies dans la doc de l'image. Toujours ajouter TZ=Europe/Paris si l'image le supporte.
• Ports : commenter les ports HTTP non nécessaires si SWAG/reverse proxy gère l'accès
• Network : toujours swag_lan (external) comme réseau par défaut
• restart : toujours always

4. Déploiement via Portainer

Utiliser le skill portainer pour déployer ou mettre à jour la stack :

• Endpoint id : 2
• Créer une nouvelle stack avec le compose généré
• Ou ajouter le service à une stack existante si regroupement logique souhaité

5. SWAG / Reverse proxy

Si l'app a une interface web, proposer à Christophe de configurer un sous-domaine via SWAG. Voir les configs proxy disponibles sur linuxserver.io/swag.

Exemple complet

Voir references/example-heimdall.yml pour un exemple de référence.