HYPHApar S33D
Documentation › Intégrations

Applications auto-hébergées : Nextcloud, Jellyfin, Syncthing, Immich, Forgejo, Matrix, Home Assistant, Mastodon

Huit applications que l'on héberge chez soi, lues par leur interface native : santé, utilisateurs, files de tâches, stockage, synchronisation, avec des modèles de moniteurs et un tableau prêt pour chacune.

En un coup d'œil

Chaque application est lue par le moyen le plus direct qu'elle offre : son API quand ses mesures Prometheus ne disent pas l'essentiel (Nextcloud, Jellyfin, Syncthing, Immich), sinon un profil du lecteur OpenMetrics. Tout a été éprouvé contre le vrai logiciel lancé en conteneur dans un environnement d'essai de S33D (dernière colonne).

ApplicationCollecteActivationEspace de nomsÉprouvé sur
Nextcloudsonde : status.php et API serverinfodès que url est poséenextcloud.*Nextcloud 35.0.3 (serverinfo 7.0.0)
Jellyfinsonde : /health et API du serveurauto sur 127.0.0.1:8096jellyfin.*Jellyfin 12.4.0
Syncthingsonde : API RESTauto sur 127.0.0.1:8384syncthing.*Syncthing 2.1.7 (deux appareils reliés)
Immichsonde : API du serveurdès que url est poséeimmich.*Immich 3.4.2
Gitea et Forgejoprofil gitea ou forgejo (/metrics)à déclarergitea.*Gitea 28.4.0, Forgejo 13.0.5
Matrix Synapseprofil synapse (/_synapse/metrics)à déclarersynapse.*Synapse 1.165.0
Home Assistantprofil homeassistant (/api/prometheus)à déclarerhomeassistant.*Home Assistant 2026.11.2
Mastodonprofils mastodon et mastodon_streamingà déclarermastodon.*, mastodon_streaming.*Mastodon 4.7.6 (web, Sidekiq, streaming)

Les sondes ne font que lire : aucune écriture, aucune tâche lancée, aucun appel qui ferait contacter un service extérieur par l'application. Les clés se posent de préférence dans un fichier lisible par l'agent seul (api_key_file, token_file), relu à chaque relevé : une clé changée est prise sans relancer l'agent. hypha-agent check-config les affiche masquées.

integrations:
  nextcloud: {url: "https://cloud.exemple", token_file: /etc/hypha/nextcloud.token}
  jellyfin: {api_key_file: /etc/hypha/jellyfin.key}          # url par défaut : http://127.0.0.1:8096
  syncthing: {api_key_file: /etc/hypha/syncthing.key}        # url par défaut : http://127.0.0.1:8384
  immich: {url: "http://127.0.0.1:2283", api_key_file: /etc/hypha/immich.key}
  openmetrics:
    - profile: forgejo                                       # ou gitea
      bearer_token_file: /etc/hypha/forgejo-metrics.token
    - profile: synapse
    - profile: homeassistant
      bearer_token_file: /etc/hypha/homeassistant.token
    - {profile: mastodon, name: mastodon-web, url: "http://127.0.0.1:9394/metrics"}
    - {profile: mastodon, name: mastodon-sidekiq, url: "http://127.0.0.1:9395/metrics"}
    - profile: mastodon_streaming

Les quatre sondes acceptent des instances (plusieurs Nextcloud ou Syncthing sur une machine, chacun avec son name, étiquette instance_name).

Nextcloud

La sonde lit status.php sans compte (installé, mode maintenance, mise à niveau de la base en attente, version), puis l'API de l'application serverinfo (livrée et active d'office). Le plus simple est un jeton propre à serverinfo, qui ne donne accès qu'à ces statistiques :

sudo -u www-data php occ config:app:set serverinfo token --value "$(openssl rand -hex 24)"

Le même jeton va dans token_file (en-tête NC-Token). À défaut, un compte administrateur et un mot de passe d'application (username, password).

Les comptes de fichiers et de stockages sont ceux que serverinfo tient à jour par sa tâche de fond (occ serverinfo:update-storage-statistics les rafraîchit). Les mises à jour d'applications ne sont pas lues : la sonde garde les réglages par défaut de serverinfo (skipApps, skipUpdate), pour ne jamais faire interroger le magasin d'applications par Nextcloud.

Nextcloud 35 (vu dans l'essai) publie aussi /metrics au format OpenMetrics (comptes actifs, sessions, tâches de fond), réservé par défaut à la boucle locale (openmetrics_allowed_clients dans config.php) : le lecteur générique peut le lire, la sonde suffit pour l'essentiel.

Jellyfin

Sans clé, la sonde lit /health (Healthy, Degraded, Unhealthy) et la version publique. Avec une clé d'API (Tableau de bord › Clés d'API), elle lit aussi les sessions, les bibliothèques et les tâches planifiées. Jellyfin 12.4 n'accepte la clé que dans l'en-tête Authorization: MediaBrowser Token="…" (X-Emby-Token et ?api_key= sont refusés) : c'est ce que fait l'agent.

Le /metrics de Jellyfin (EnableMetrics dans system.xml) ne publie que des mesures du moteur .NET et des requêtes HTTP : le lecteur générique peut le lire en plus.

Syncthing

Sans clé, la sonde lit /rest/noauth/health. Avec la clé de l'interface (Actions › Configuration › Interface graphique › Clé d'API, en-tête X-API-Key), elle lit chaque minute les appareils, les connexions, les dossiers et les erreurs. /rest/db/status étant coûteux pour Syncthing, la sonde en fait une requête par dossier et par minute, et s'arrête à 100 dossiers.

Syncthing 2.1 publie aussi /metrics (clé exigée) : états et volumes des dossiers sous forme de codes, sans les erreurs ni les appareils absents ; la sonde REST les donne en clair.

Immich

Sans clé, la sonde lit /api/server/ping et la version. Avec une clé d'API (Paramètres du compte › Clés d'API) portant les permissions server.storage, server.statistics et job.read (et rien d'autre), elle lit le disque de la photothèque, le nombre de photos et de vidéos et les files de tâches.

Les mesures Prometheus d'Immich (IMMICH_TELEMETRY_INCLUDE=all, ports 8081 et 8082) donnent surtout des durées internes et l'activité des files, sans le disque ni l'état des files : le lecteur générique peut les lire en plus. Piège vu sur Immich 3.4.2 : avec l'adresse d'écoute par défaut (::), ces deux ports répondent « 400 Bad Request » à toute requête ; poser IMMICH_HOST=0.0.0.0 les rend lisibles.

Gitea et Forgejo

Dans app.ini : [metrics] ENABLED = true (ou GITEA__metrics__ENABLED=true, FORGEJO__metrics__ENABLED=true en conteneur). Avec [metrics] TOKEN = …, le jeton va dans bearer_token_file. Forgejo publie les mêmes familles gitea_* que Gitea : les profils gitea et forgejo sont identiques et donnent les mêmes noms gitea.*, donc les mêmes tableaux et moniteurs (instance_name les distingue).

Ce sont des comptes de la base (jauges) : la santé de la forge se suit par openmetrics.can_connect et un test synthétique HTTP sur l'interface.

Matrix Synapse

Dans homeserver.yaml : enable_metrics: true et un écouteur dédié, lié à la boucle locale.

listeners:
  - port: 9000
    type: metrics
    bind_addresses: ['127.0.0.1']

La santé publique de Synapse se suit en plus par un test synthétique HTTP sur /health (réponse OK) de l'écouteur client.

Home Assistant

Dans configuration.yaml : prometheus: (l'intégration Prometheus native). Sa route /api/prometheus demande un jeton d'accès longue durée (Profil › Sécurité › Jetons d'accès longue durée), posé dans bearer_token_file.

Une maison de plusieurs centaines d'entités dépasse le plafond de 2 000 séries d'une cible (deux séries par entité au moins) : relever max_series dans l'entrée, ou écarter des domaines dans la conf de l'intégration Prometheus de Home Assistant (filter). Les autres familles (homeassistant_sensor_unit_*, dates de mise à jour) s'ajoutent par metrics et rename.

Mastodon

Variables d'environnement de Mastodon (vues sur la 4.7.6) : MASTODON_PROMETHEUS_EXPORTER_ENABLED=true, et soit MASTODON_PROMETHEUS_EXPORTER_LOCAL=true (le web et Sidekiq servent chacun leur /metrics sur MASTODON_PROMETHEUS_EXPORTER_PORT, 9394 par défaut : un port par service quand ils tournent sur la même machine), soit le processus bin/prometheus_exporter qui les regroupe. MASTODON_PROMETHEUS_EXPORTER_SIDEKIQ_DETAILED_METRICS=true ajoute les files de Sidekiq (taille, retard), MASTODON_PROMETHEUS_EXPORTER_WEB_DETAILED_METRICS=true les requêtes HTTP. Le serveur de streaming publie /metrics sur son port (4000) sans réglage.

Les mesures de Puma et des files de Sidekiq sont relevées par Mastodon à intervalle : juste après un redémarrage, elles manquent quelques instants. La santé publique se suit en plus par un test synthétique HTTP sur /health (réponse OK) et /api/v1/streaming/health.

Modèles de moniteurs

Dans Moniteurs › Nouveau › Depuis un modèle, famille Applications auto-hébergées :

Tableaux prêts

Tableaux de bord › Catalogue, famille Applications auto-hébergées : Nextcloud, Jellyfin, Syncthing, Immich, Gitea et Forgejo, Matrix Synapse, Home Assistant, Mastodon (avec le streaming), installés d'un clic puis modifiables comme des tableaux ordinaires.

Ce qui a été éprouvé

Chaque application a tourné en conteneur dans l'environnement d'essai de S33D, avec des comptes et des données d'essai créés pour l'occasion. L'agent l'a d'abord lue à blanc, puis l'agent 0.11 de l'hôte d'essai a envoyé ses mesures à HYPHA : tous les contrôles et toutes les mesures des tableaux prêts y ont été vus, sauf synapse.push.processed et synapse.push.failed (aucune passerelle de notifications poussées dans l'essai).

Pannes provoquées, vues puis revenues à la normale : Nextcloud en mode maintenance (nextcloud.status critique) ; Jellyfin, Home Assistant et le Sidekiq de Mastodon arrêtés (critique) ; second Syncthing arrêté (syncthing.can_connect critique, et sur le premier, appareil déconnecté en avertissement avec sa dernière date de connexion) ; dossier Syncthing privé de son marqueur .stfolder (critique) ; file d'Immich mise en pause (avertissement).

Restent à voir sur une installation réelle : transcodage de Jellyfin, poussées de Synapse et fédération entre deux serveurs Matrix, maison Home Assistant de plusieurs centaines d'entités (l'essai en comptait 127), Mastodon fédéré sous charge, quotas d'Immich ; les tâches planifiées en échec de Jellyfin et les tâches en échec d'Immich ne sont éprouvées qu'en tests, sur des réponses réelles modifiées.

Mise à jour : 21 novembre 2026