Ajouter une Application

Ceci est la référence complète pour ajouter une nouvelle app au Yundera App Store. Pour un aperçu rapide, voir Vue d'ensemble des Contributions.

Template minimal (SSO via AppShield)

Le pattern recommandé : un sidecar AppShield protège votre backend et fournit le SSO Yundera. Le backend n'est jamais exposé directement — seul le sidecar reçoit les labels de routage.

name: myapp   # alphanumérique minuscule + tiret, ne commençant pas par un chiffre

services:
  myapp:                                    # ← Sidecar AppShield (face publique)
    image: ghcr.io/yundera/appshield:2.0.3  # fixer la version ; jamais :latest
    container_name: myapp                   # DOIT être égal au name: de premier niveau
    restart: unless-stopped
    user: "root"
    expose:
      - 80
    labels:
      caddy_0: myapp-${APP_DOMAIN}
      caddy_0.import: gateway_tls
      caddy_0.reverse_proxy: "{{upstreams 80}}"
      caddy_1: myapp-${APP_PUBLIC_IP_DASH}.nip.io
      caddy_1.import: gateway_tls
      caddy_1.reverse_proxy: "{{upstreams 80}}"
      caddy_2: myapp-${APP_PUBLIC_IP_DASH}.sslip.io
      caddy_2.reverse_proxy: "{{upstreams 80}}"
    environment:
      AUTH_HASH: $AUTH_HASH
      BACKEND_HOST: "myapp-backend"
      BACKEND_PORT: "80"
      LISTEN_PORT: "80"
      OIDC_REGISTRAR_URL: "http://auth-registrar:9092"
      REDIRECT_HOST_SUFFIXES: "${APP_DOMAIN},${APP_PUBLIC_IP_DASH}.nip.io,${APP_PUBLIC_IP_DASH}.sslip.io"
      CREDENTIAL_VALIDATE_URL: "http://casaos-oidc-bridge:8090/validate"
    depends_on:
      - myapp-backend
    cpu_shares: 80
    networks:
      - pcs

  myapp-backend:                            # ← app réelle (interne uniquement)
    image: someimage:1.2.3
    container_name: myapp-backend
    restart: unless-stopped
    user: "0:0"
    expose:
      - 80
    environment:
      TZ: $TZ
    volumes:
      - /DATA/AppData/$AppID/data/:/app/data/
    cpu_shares: 50
    networks:
      - pcs

networks:
  pcs:
    name: pcs
    external: true

x-casaos:
  architectures:
    - amd64
    - arm64
  main: myapp
  index: /?hash=$AUTH_HASH
  webui_port: 80
  author: Yundera Team
  category: Utilities
  developer: OriginalDevName
  icon: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/MyApp/icon.png
  thumbnail: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/MyApp/thumbnail.png
  screenshot_link:
    - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/MyApp/screenshot-1.png
  title:
    en_us: My App
  tagline:
    en_us: One-line description
  description:
    en_us: |
      Full description here.

Convention de nommage (critique)

Le container_name du sidecar doit être égal au name: de premier niveau. C'est structurel : le registrar auth dérive le client_id OIDC du nom du conteneur via une recherche PTR sur le réseau pcs. S'ils ne correspondent pas, l'enregistrement SSO échoue silencieusement.

name: myapp
services:
  myapp:
    container_name: myapp   # ← DOIT être égal à name:

Règles :

• name: / sidecar container_name : alphanumérique minuscule + tirets, ne commençant pas par un chiffre.
• Les labels Caddy vont uniquement sur le sidecar — jamais sur le backend.
• Le backend n'a pas de ports: ni de labels Caddy.
• Jamais utiliser auth-${APP_DOMAIN} dans un label Caddy — cela entre en conflit avec l'Authelia du PCS.

Référence des variables d'environnement AppShield

Variable	Requis	Objectif
AUTH_HASH	Oui	Token injecté ; associer avec index: /?hash=$AUTH_HASH
BACKEND_HOST	Oui	Nom DNS interne du conteneur protégé
BACKEND_PORT	Oui	Port d'écoute du backend
LISTEN_PORT	Oui	Port d'écoute d'AppShield
OIDC_REGISTRAR_URL	Oui	http://auth-registrar:9092 — active OIDC
REDIRECT_HOST_SUFFIXES	Oui	Hôtes de redirection OIDC valides
CREDENTIAL_VALIDATE_URL	Oui	Valide la session auprès du bridge PCS
USER / PASSWORD	Optionnel	Porte d'auth basique supplémentaire (ex. $APP_DEFAULT_PASSWORD)
ALLOWED_PATHS	Optionnel	Chemins accessibles avec seulement le token hash

Chemins de volumes

volumes:
  - /DATA/AppData/$AppID/config/:/app/config    # config app
  - /DATA/AppData/$AppID/data/:/app/data        # données app / BDD
  - /DATA/Media/Music/:/music:ro                # médias partagés (lecture seule)

Important

Ajoutez toujours un / final côté hôte des chemins de volumes. Sans cela, CasaOS ne peut pas résoudre $AppID correctement et crée des fichiers directement dans /DATA/AppData/ au lieu du dossier de l'app.

# Correct
- /DATA/AppData/$AppID/config/:/etc/myapp

# Incorrect — les fichiers se retrouvent dans /DATA/AppData/ directement
- /DATA/AppData/$AppID/config:/etc/myapp

Les répertoires utilisateur (/DATA/Documents/, /DATA/Downloads/, /DATA/Media/, /DATA/Gallery/) nécessitent user: $PUID:$PGID. Les conteneurs AppData uniquement peuvent utiliser user: 0:0.

Limites de ressources

cpu_shares est requis sur chaque service. Pour les backends lourds, définissez aussi des limites strictes :

cpu_shares	Cas d'usage
80	Sidecars, frontends web
70	App principale avec tâches de fond
50	Services backend standard
30	Bases de données, caches
20	ML / traitement par lots

cpu_shares: 50
deploy:
  resources:
    limits:
      memory: 2G
      cpus: '1.0'

Commandes de pré-installation

Exécutées sur l'hôte avant le démarrage de tout conteneur :

x-casaos:
  pre-install-cmd: |
    mkdir -p /DATA/AppData/$AppID/config/ &&
    [ -f /DATA/AppData/$AppID/config/settings.ini ] || \
      printf '[server]\nport=80\n' > /DATA/AppData/$AppID/config/settings.ini

Règles : idempotent, non interactif, tags d'image fixés, pas de mots de passe codés en dur (utiliser $APP_DEFAULT_PASSWORD).

Variables système

Ces variables sont injectées à l'installation :

Variable	Exemple	Usage
$APP_DOMAIN	votrenom.nsl.sh	https://myapp-${APP_DOMAIN}
$APP_PUBLIC_IP_DASH	203-0-113-42	Labels nip.io / sslip.io
$AUTH_HASH	(généré)	Token AppShield
$APP_DEFAULT_PASSWORD	(généré)	Mot de passe admin initial
$APP_EMAIL	admin@votrenom.nsl.sh	Email administrateur
$AppID	myapp	Chemins de volumes : /DATA/AppData/$AppID/
$PUID / $PGID	1000 / 1000	Propriété des fichiers
$TZ	Asia/Seoul	Fuseau horaire