Irbis_OS-Release/CONTRIBUTING_APPS.md

🚀 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.

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 :

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 :

   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.

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 :

   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

{
  "$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

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.