---
name: qnap-docker
description: 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 :

```bash
# 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

```yaml
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](https://docs.linuxserver.io/general/swag/).

## Exemple complet

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