diff --git a/CONTRIBUTING_APPS.md b/CONTRIBUTING_APPS.md index 7568d57..13dd0cd 100644 --- a/CONTRIBUTING_APPS.md +++ b/CONTRIBUTING_APPS.md @@ -4,6 +4,24 @@ 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 ? @@ -13,79 +31,100 @@ L'App Store d'Irbis OS est conçu pour permettre à la communauté de proposer d 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`). +2. **Créez un dossier** dans `community_apps/` au nom de votre application en minuscules (ex: `community_apps/mon-application/`). -3. **Remplissez la définition** en suivant le schéma officiel [`schemas/app-template.schema.json`](./schemas/app-template.schema.json). +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. **Validez localement** votre fichier avec la commande : +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 ``` -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 ! +7. **Ouvrez votre Pull Request** sur Gitea (`https://git.nebulia.tech/SlyderSlash/Irbis_OS-Release/pulls`). --- -## 🛠️ Structure du fichier JSON d'une application - -Voici un modèle complet commenté : +## 🛠️ 1. Modèle de `app.json` ```json { - "$schema": "../schemas/app-template.schema.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 de l'application affichée sur la vignette du magasin.", + "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.", - "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", + "developer": "Nom du Développeur ou Équipe Open Source", "website": "https://mon-application.org", "rating": 4.9, - "downloads": "500K", - "sizeMb": 250, + "downloads": "250K", + "sizeMb": 180, "license": "MIT", - "image": "mon-organisation/mon-application:latest", - "defaultPort": 8080, + + "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": [ { - "privatePort": 8080, + "name": "Interface Web", + "description": "Port HTTP principal d'administration", + "privatePort": 80, "defaultPublicPort": 8080, - "description": "Interface Web d'administration", - "type": "tcp" + "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": "Dossier de stockage persistant", + "description": "Données persistantes de l'application", "required": true - }, - { - "defaultHostPath": "/mnt/storage/configs/mon-application", - "containerPath": "/config", - "description": "Fichiers de configuration", - "required": false } ], + "env": [ + { + "key": "ADMIN_USER", + "defaultValue": "admin", + "label": "Nom d'utilisateur administrateur", + "required": true + }, { "key": "TZ", "defaultValue": "Europe/Paris", - "label": "Fuseau Horaire", + "label": "Fuseau horaire", "required": false - }, - { - "key": "ADMIN_PASSWORD", - "defaultValue": "", - "label": "Mot de passe administrateur initial", - "required": true } ] } @@ -93,22 +132,30 @@ Voici un modèle complet commenté : --- -## 🏷️ Catégories supportées +## 🐳 2. Modèle de `docker-compose.yml` -- `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...) +```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} +``` --- -## 🔒 Règles et Bonnes Pratiques +## 🔒 3. Critères d'Acceptation d'une Pull Request -- **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). +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//` pour garantir la compatibilité avec les snapshots Btrfs et les sauvegardes du NAS. +- Être validée avec succès par `pnpm validate:apps`.