162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# 🚀 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`.
|