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.

---

📋 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 fichier JSON dans le dossier community_apps/ nommé selon l'identifiant de votre application en minuscules (ex: community_apps/mon-application.json).

3. Remplissez la définition en suivant le schéma officiel schemas/app-template.schema.json.

4. Validez localement votre fichier avec la commande :

   pnpm validate:apps
   

5. Ouvrez votre Pull Request sur Gitea (https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release/pulls) en décrivant brièvement l'application et en confirmant qu'elle a été testée localement sur Irbis OS. Dès que la PR est validée et fusionnée, l'application apparaît automatiquement dans l'App Store de tous les serveurs Irbis OS connectés !

---

🛠️ Structure du fichier JSON d'une application

Voici un modèle complet commenté :

{
  "$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 de l'application 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.",
  "icon": "https://example.com/logo-mon-application.png",
  "screenshots": [
    "https://example.com/screenshot1.png"
  ],
  "category": "productivity",
  "version": "1.0.0",
  "developer": "Nom du Créateur ou Projet Open Source",
  "website": "https://mon-application.org",
  "rating": 4.9,
  "downloads": "500K",
  "sizeMb": 250,
  "license": "MIT",
  "image": "mon-organisation/mon-application:latest",
  "defaultPort": 8080,
  "ports": [
    {
      "privatePort": 8080,
      "defaultPublicPort": 8080,
      "description": "Interface Web d'administration",
      "type": "tcp"
    }
  ],
  "volumes": [
    {
      "defaultHostPath": "/mnt/storage/mon-application/data",
      "containerPath": "/data",
      "description": "Dossier de stockage persistant",
      "required": true
    },
    {
      "defaultHostPath": "/mnt/storage/configs/mon-application",
      "containerPath": "/config",
      "description": "Fichiers de configuration",
      "required": false
    }
  ],
  "env": [
    {
      "key": "TZ",
      "defaultValue": "Europe/Paris",
      "label": "Fuseau Horaire",
      "required": false
    },
    {
      "key": "ADMIN_PASSWORD",
      "defaultValue": "",
      "label": "Mot de passe administrateur initial",
      "required": true
    }
  ]
}

---

🏷️ Catégories supportées

• media : Streaming, serveurs multimédia (Plex, Jellyfin, Navidrome...)
• cloud : Stockage distant, synchronisation (Nextcloud, Owncloud, Seafile...)
• productivity : Bureautique, notes, automatisation (Home Assistant, N8N...)
• security : Mots de passe, VPN, gestionnaires de secrets (Vaultwarden, WireGuard...)
• utilities : Téléchargements, sauvegardes, bases de données (qBittorrent, Duplicati...)
• development : Outils de dev, IDE web, CI/CD (Gitea, Code-Server...)
• home_automation : Domotique, gestion IoT (Zigbee2MQTT, Node-RED...)
• network : Serveurs DNS, proxys, pare-feu (AdGuard Home, Nginx Proxy Manager...)

---

🔒 Règles et Bonnes Pratiques

• Images Docker vérifiées : Utilisez de préférence les images officielles Docker Hub ou LinuxServer.io (lscr.io/linuxserver/..., ghcr.io/...).
• Chemins de volumes : Les chemins hôtes par défaut doivent impérativement commencer par /mnt/storage/ afin d'exploiter la partition de stockage principale du NAS.
• Ports sans collision : Veillez à ce que le defaultPort n'entre pas en conflit direct avec les services système fondamentaux d'Irbis OS (4000, 22, 80, 443).
• Icône de qualité : Fournissez une URL HTTPS directe vers une image PNG ou SVG au format carré (au moins 128x128 px).