SlyderSlash/Irbis_OS-Release
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 70 Wiki Activity

docs: update CONTRIBUTING_APPS.md for v1.7.0

Browse Source
This commit is contained in:
SlyderSlash
2026-09-29 19:45:58 +02:00
parent f877238962
commit 81fddd20e6
1 changed files with 96 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
CONTRIBUTING_APPS.md
View File

@@ -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)**. 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 ? ## 📋 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 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 ```bash
pnpm validate:apps 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 ## 🛠️ 1. Modèle de `app.json`
Voici un modèle complet commenté :
```json ```json
{ {
"$schema": "../schemas/app-template.schema.json", "$schema": "../../schemas/app-template.schema.json",
"id": "mon-application", "id": "mon-application",
"name": "Mon Application", "name": "Mon Application",
"tagline": "Une phrase d'accroche courte et percutante (max 150 caractères)", "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.", "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", "category": "productivity",
"version": "1.0.0", "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", "website": "https://mon-application.org",
"rating": 4.9, "rating": 4.9,
"downloads": "500K", "downloads": "250K",
"sizeMb": 250, "sizeMb": 180,
"license": "MIT", "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": [ "ports": [
{ {
"privatePort": 8080, "name": "Interface Web",
"description": "Port HTTP principal d'administration",
"privatePort": 80,
"defaultPublicPort": 8080, "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": [ "volumes": [
{ {
"defaultHostPath": "/mnt/storage/mon-application/data", "defaultHostPath": "/mnt/storage/mon-application/data",
"containerPath": "/data", "containerPath": "/data",
"description": "Dossier de stockage persistant", "description": "Données persistantes de l'application",
"required": true "required": true
},
{
"defaultHostPath": "/mnt/storage/configs/mon-application",
"containerPath": "/config",
"description": "Fichiers de configuration",
"required": false
} }
], ],
"env": [ "env": [
{
"key": "ADMIN_USER",
"defaultValue": "admin",
"label": "Nom d'utilisateur administrateur",
"required": true
},
{ {
"key": "TZ", "key": "TZ",
"defaultValue": "Europe/Paris", "defaultValue": "Europe/Paris",
"label": "Fuseau Horaire", "label": "Fuseau horaire",
"required": false "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...) ```yaml
- `cloud` : Stockage distant, synchronisation (Nextcloud, Owncloud, Seafile...) services:
- `productivity` : Bureautique, notes, automatisation (Home Assistant, N8N...) mon-application:
- `security` : Mots de passe, VPN, gestionnaires de secrets (Vaultwarden, WireGuard...) image: mon-organisation/mon-application:latest
- `utilities` : Téléchargements, sauvegardes, bases de données (qBittorrent, Duplicati...) container_name: mon-application
- `development` : Outils de dev, IDE web, CI/CD (Gitea, Code-Server...) restart: unless-stopped
- `home_automation` : Domotique, gestion IoT (Zigbee2MQTT, Node-RED...) ports:
- `network` : Serveurs DNS, proxys, pare-feu (AdGuard Home, Nginx Proxy Manager...) - "${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/...`). Pour être validée et publiée, toute application doit :
- **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. - Utiliser une image Docker publique, réputée et maintenue.
- **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`). - Ne pas nécessiter de droits root privilégiés (`privileged: true`) sauf besoin matériel justifié.
- **Icône de qualité** : Fournissez une URL HTTPS directe vers une image PNG ou SVG au format carré (au moins 128x128 px). - 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`.