# 🚀 Guide de Contribution - Proposer une Application pour Irbis OS

Merci de contribuer à l'écosystème **Irbis OS** ! ❄️

L'App Store d'Irbis OS est conçu pour permettre à la communauté de proposer de nouvelles applications conteneurisées (Docker) via une simple **Pull Request** sur notre dépôt public Gitea : **[https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release](https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release)**.

Dès que votre Pull Request est validée et fusionnée sur ce dépôt public, votre application apparaît **instantanément dans l'App Store de tous les serveurs Irbis OS connectés**, sans qu'aucune mise à jour de l'OS ne soit nécessaire !

---

## 📁 Nouvelle Architecture : 1 Dossier par Application

Chaque application possède son propre sous-dossier dans `community_apps/` nommé selon son identifiant en minuscules :

```text
community_apps/
└── mon-application/
    ├── app.json             # Fiche descriptive de l'application & paramètres UI
    ├── docker-compose.yml   # Stack Docker technique (services, images, réseaux, volumes)
    ├── icon.png             # Image de garde (icône PNG ou SVG carré)
    ├── screenshot1.png      # Capture d'écran de démo #1
    └── screenshot2.png      # Capture d'écran de démo #2
```

---

## 📋 Comment proposer une nouvelle application ?

1. **Forkez** le dépôt public Irbis OS Releases (`https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release`) et créez une branche dédiée :
   ```bash
   git checkout -b app/mon-application
   ```

2. **Créez un dossier** dans `community_apps/` au nom de votre application en minuscules (ex: `community_apps/mon-application/`).

3. **Créez le fichier `app.json`** en vous basant sur le modèle ci-dessous et le schéma officiel [`schemas/app-template.schema.json`](./schemas/app-template.schema.json).

4. **Créez le fichier `docker-compose.yml`** contenant la définition officielle de vos conteneurs. Toutes les informations techniques lourdes (images, réseaux, restart policy) sont déléguées à ce fichier Docker Compose afin de ne pas doubler les demandes.

5. **Ajoutez vos visuels** dans le dossier (`icon.png` et les éventuelles captures de démo).

6. **Validez localement** votre application avec la commande :
   ```bash
   pnpm validate:apps
   ```

7. **Ouvrez votre Pull Request** sur Gitea (`https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release/pulls`).

---

## 🛠️ 1. Modèle de `app.json`

```json
{
  "$schema": "../../schemas/app-template.schema.json",
  "id": "mon-application",
  "name": "Mon Application",
  "tagline": "Une phrase d'accroche courte et percutante (max 150 caractères)",
  "description": "Description concise affichée sur la vignette du magasin.",
  "longDescription": "Description détaillée expliquant les fonctionnalités principales, les cas d'usage et les avantages pour un serveur NAS ou Home Lab.",
  "category": "productivity",
  "version": "1.0.0",
  "developer": "Nom du Développeur ou Équipe Open Source",
  "website": "https://mon-application.org",
  "rating": 4.9,
  "downloads": "250K",
  "sizeMb": 180,
  "license": "MIT",
  
  "icon": "icon.png",
  "screenshots": [
    "screenshot1.png",
    "screenshot2.png"
  ],

  "firstStartTip": "Lors du premier accès, utilisez l'identifiant par défaut 'admin' et suivez l'assistant de configuration initial pour sécuriser vos accès.",

  "composeFile": "docker-compose.yml",

  "nginx": {
    "recommendedSubdomain": "monapp",
    "enableSsl": true,
    "mainPort": 80
  },

  "ports": [
    {
      "name": "Interface Web",
      "description": "Port HTTP principal d'administration",
      "privatePort": 80,
      "defaultPublicPort": 8080,
      "type": "tcp",
      "protocol": "http",
      "isDefaultNginxTarget": true
    },
    {
      "name": "API & WebSocket",
      "description": "Flux temps réel et synchronisation",
      "privatePort": 3000,
      "defaultPublicPort": 3000,
      "type": "tcp",
      "protocol": "http",
      "isDefaultNginxTarget": false
    }
  ],

  "volumes": [
    {
      "defaultHostPath": "/mnt/storage/mon-application/data",
      "containerPath": "/data",
      "description": "Données persistantes de l'application",
      "required": true
    }
  ],

  "env": [
    {
      "key": "ADMIN_USER",
      "defaultValue": "admin",
      "label": "Nom d'utilisateur administrateur",
      "required": true
    },
    {
      "key": "TZ",
      "defaultValue": "Europe/Paris",
      "label": "Fuseau horaire",
      "required": false
    }
  ]
}
```

---

## 🐳 2. Modèle de `docker-compose.yml`

```yaml
services:
  mon-application:
    image: mon-organisation/mon-application:latest
    container_name: mon-application
    restart: unless-stopped
    ports:
      - "${MON_APP_PORT:-8080}:80"
      - "${MON_APP_API_PORT:-3000}:3000"
    volumes:
      - "${MON_APP_DATA_PATH:-/mnt/storage/mon-application/data}:/data"
    environment:
      - ADMIN_USER=${ADMIN_USER:-admin}
      - TZ=${TZ:-Europe/Paris}
```

---

## 🔒 3. Critères d'Acceptation d'une Pull Request

Pour être validée et publiée, toute application doit :
- Utiliser une image Docker publique, réputée et maintenue.
- Ne pas nécessiter de droits root privilégiés (`privileged: true`) sauf besoin matériel justifié.
- Persister ses données sous `/mnt/storage/<id>/` pour garantir la compatibilité avec les snapshots Btrfs et les sauvegardes du NAS.
- Être validée avec succès par `pnpm validate:apps`.