Votre propre App Center : diffusez vos paquets QPKG depuis Git vers chaque NAS

Bucket & Code Server IDE gère un dépôt App Center sur votre NAS. Un projet QPKG créé avec Nouveau projet se compile à chaque push Git et publie le paquet signé dans ce dépôt. Vos autres NAS ajoutent l’adresse du dépôt dans App Center une seule fois, puis installent et mettent à jour vos paquets comme n’importe quelle autre application. Cloudflare Tunnel peut publier le dépôt, et Git si vous le souhaitez, sans ouvrir de port sur votre routeur.

Préparermodules, QDK, un certificat
ProjetNouveau projet, paquet QPKG
Signerdeux secrets dans Forgejo
Dépôtson adresse dans App Center
Internetun nom d’hôte des paquets

Les captures proviennent du panneau, chaque champ rempli comme le décrit ce guide. Les adresses sont celles d’un NAS à l’adresse 192.168.1.20, et les noms publiés sont des exemples sous example.com.

01Avant de commencer

Git, CI et l’Éditeur doivent être activés : un administrateur active chacun avec son bouton dans Vue d’ensemble (Activer Git, Activer Git et CI, Activer Éditeur). L’assistant Nouveau projet nécessite Git et l’Éditeur, et CI exécute le workflow du projet à chaque push.
QDK doit être installé : dans la page Toolchains, onglet QNAP, installez QNAP QDK 2.5.0.
Il vous faut un certificat de signature de code délivré par QNAP, sous forme de fichiers : certificate, private_key et, pour la chaîne, ca_certs. App Center vérifie la signature de code d’un paquet lors de son installation, et le dépôt de la page Paquets n’accepte que les paquets dotés d’une signature de code. Un certificat sur jeton matériel n’est pas pris en charge.

La carte Signature de code de la page Paquets : 1, un certificat sous forme de fichiers, pris en charge ; 2, un certificat sur jeton matériel, non pris en charge ; 3, aucun certificat, non signé

02Créer le projet

Ouvrez Nouveau projet depuis la page Git ou depuis la palette de commandes (rôle développeur).

Modèle. Sous Paquets pour QTS, choisissez Paquet QPKG et appuyez sur Suivant.
Nom et visibilité. Le nom est celui du dépôt, du dossier et du paquet : 1 à 20 lettres, chiffres, tirets ou tirets bas. Le propriétaire est votre compte ou une organisation ; laissez le projet en Privé.
Service. Choisissez comment le paquet démarre et s’arrête : Outil en ligne de commande crée un lien vers le programme dans /usr/bin, Service en arrière-plan l’exécute sous un compte qui lui est propre, Application web lui ajoute aussi le bouton Ouvrir d’App Center, et Vide ne contient que les verbes de service de base (start, stop, etc.). Vous pourrez modifier ces blocs plus tard dans la vue Projet.
Compilation. Choisissez l’environnement dans lequel le projet se compile et laissez Compiler juste après la création activé.
Publication. Activez Publier dans le dépôt App Center de ce NAS. Ce même interrupteur reste ensuite dans les réglages du projet et permet à CI de publier à chaque exécution.
Vérification. Contrôlez les étapes qui seront exécutées, puis appuyez sur Créer le projet.

La première tâche crée le dépôt dans Forgejo et le dossier projects/<name> avec le premier commit : les fichiers du modèle et le workflow .forgejo/workflows/build.yml. La première compilation n’a pas encore de certificat ; son étape de publication s’arrête donc et indique que le paquet ne porte aucune signature de code. L’interrupteur reste activé, et une fois l’étape 03 terminée, chaque push publie.

03Signer chaque compilation

Sur le NAS, placez les fichiers du certificat à côté de qpkg.cfg dans projects/<name>. Le .gitignore du modèle les garde hors de git. Une compilation dans ce dossier signe alors le paquet, et la première ligne de bvs qbuild affiche case 1. Si l’environnement n’a pas openssl ou bsdextrautils, la compilation s’arrête et indique la commande qui les ajoute.

CI extrait le dépôt sans ces fichiers et les obtient donc à partir de deux secrets. Dans Forgejo, ouvrez Réglages → Actions → Secrets du dépôt, puis appuyez deux fois sur Ajouter un secret : QPKG_CERTIFICATE avec la sortie de base64 -w0 certificate, et QPKG_PRIVATE_KEY avec celle de base64 -w0 private_key. Forgejo demande lui-même du Base64 lorsque les retours à la ligne d’une valeur doivent être conservés. Un certificat avec chaîne nécessite un troisième secret, QPKG_CA_CERTS, et une troisième ligne dans la première étape qui l’écrit dans ca_certs.

Boîte de dialogue Ajouter un secret de Forgejo : Nom QPKG_CERTIFICATE, Valeur une ligne Base64, boutons Annuler et Confirmer

Ajoutez ensuite deux étapes à .forgejo/workflows/build.yml : l'une qui écrit les fichiers avant la compilation, juste après le checkout, et l'autre en fin de liste qui les supprime quel que soit le résultat. Les étapes propres au modèle restent inchangées.

# .forgejo/workflows/build.yml: the two new steps, in the template's steps list
    steps:
      - uses: actions/checkout@v4
      - name: certificate from the secrets
        run: |
          printf '%s' "$CERT" | base64 -d > certificate
          printf '%s' "$KEY" | base64 -d > private_key
          chmod 600 private_key
        env:
          CERT: ${{ secrets.QPKG_CERTIFICATE }}
          KEY: ${{ secrets.QPKG_PRIVATE_KEY }}
      # the template's build and publish step follows here, unchanged
      - name: remove the certificate
        if: always()
        run: rm -f certificate private_key ca_certs

04Chaque push publie

Chaque push vers le dépôt lance le workflow sur le runner propre au NAS. Il compile le paquet et le publie avec --latest, de sorte que repo.xml indique immédiatement la nouvelle version et qu'App Center la propose à sa prochaine vérification. Une compilation non signée n'est pas publiée : l'exécution se termine par un avertissement qui en donne la raison.

La page du projet (Projets, ou la barre latérale de l'éditeur) exécute les mêmes étapes à la main : Compiler, Recompiler, Déploiement de test (réservé aux administrateurs, paquets signés uniquement) et Publier.

Le pipeline d'un projet QPKG : compilation dans ubuntu2404-builder avec Compiler et Recompiler ; le Test de déploiement exige un paquet signé numériquement ; Publication indique que la compilation n'est pas signée, que le dépôt n'accepte que les paquets signés, et que la CI publie aussi dans le dépôt App Center ; Publier sur le web ne peut pas s'exécuter ici

Sa carte Réglages contient l'interrupteur Publier dans le dépôt App Center. Tant qu'il est désactivé, une exécution de la CI ignore la publication et affiche un avis.

Publier dans le dépôt App Center, activé : la CI du projet ajoute ses paquets au dépôt App Center de ce NAS

La page Paquets liste chaque paquet avec sa dernière version et sa signature. Une version qu'un développeur y téléverse à la main attend qu'un administrateur en fasse la dernière version.

Paquets publiés : nom, dernière version, architectures, signé, versions et date de publication de chacune

05Ajoutez le dépôt sur vos autres NAS

Copiez l'adresse de la carte Adresse pour App Center sur la page Paquets.
Sur l'autre NAS : App Center → ⚙ Paramètres → Dépôt d'applications → Ajouter. Donnez-lui un nom, collez l'adresse et appuyez sur Ajouter.
Vos paquets figurent sous ce nom dans la colonne de gauche d'App Center. Installez-les là. Lorsque le dépôt indique une version plus récente, App Center la propose comme mise à jour.

Cette adresse LAN fonctionne pour les NAS de votre réseau. Pour un NAS situé ailleurs, publiez le dépôt sur Internet.

06Sur Internet avec Cloudflare Tunnel

Le paquet embarque cloudflared, qui ouvre depuis le NAS une connexion sortante vers Cloudflare : aucun port du routeur n'est ouvert, et Cloudflare détient les certificats des noms. Il vous faut un domaine dont le DNS est chez Cloudflare et un jeton API pour cette zone (dash.cloudflare.com, My Profile → API Tokens) avec quatre autorisations : Account, Cloudflare Tunnel, Edit ; Zone, DNS, Edit ; Zone, Cache Rules, Edit ; Zone, Cache Purge, Purge. Si le jeton comporte le filtrage par adresse IP client, ajoutez-y les deux adresses publiques du NAS, IPv4 et IPv6.

Nom	Ce qu'il sert
Nom d’hôte des paquets `qpkg.example.com`	uniquement GET et HEAD de `/repo/`, soit tout ce dont App Center a besoin sur vos autres NAS
Nom d’hôte principal `code.example.com`	le panneau, Forgejo sous `/git/` pour cloner et pousser en HTTPS, le dépôt en lecture seule, la vue web des dépôts publics et le guide d'utilisation

Pour un nom d'hôte principal, activez d'abord Navigation publique sur la page Git et appuyez sur Enregistrer et redémarrer Forgejo : la page Publication refuse un nom d'hôte principal tant que ce réglage est désactivé. Les dépôts marqués privés restent cachés.
Ouvrez Publication sous Administration (administrateurs seulement). Saisissez les noms et le jeton, gardez Préréglages de cache activé et appuyez sur Publier. Le paquet vérifie d'abord tout chez Cloudflare, ne modifie rien là-bas si une vérification échoue, et indique quoi corriger.
Il crée ensuite le tunnel, fait pointer chaque nom vers lui et démarre cloudflared. La carte Tunnel affiche les connexions.
L'adresse App Center de la page Paquets désigne désormais le nom d'hôte des paquets. Ajoutez cette adresse sur les NAS hors de votre réseau.
Avec un nom d'hôte principal, indiquez son adresse dans URL publique, sur la page Réseau, afin que les liens de Forgejo et les adresses de clonage HTTPS l'utilisent.

Git sur SSH ne passe pas par le tunnel. De l'extérieur, clonez et poussez en HTTPS, ou redirigez un port du routeur vers le port Git sur SSH (9952) et réglez Hôte SSH dans les URL de clonage sur la page Réseau.
Cloudflare accepte les requêtes jusqu'à 100 Mo. Poussez ou téléversez tout ce qui est plus gros via l'adresse LAN.
Une publication dans le dépôt retire aussitôt repo.xml du cache de Cloudflare, afin qu'App Center voie la nouvelle version à sa prochaine vérification.

07Ce qu'Internet atteint

La page Publication liste ce que sert chaque nom, ainsi que les règles de cache à côté.

Ce qu'Internet atteint : le nom d'hôte principal sert le panneau, Forgejo, la vue web et le dépôt de paquets, l'éditeur seulement tant que son interrupteur est activé, jamais WebDAV ; le nom d'hôte des paquets sert uniquement GET et HEAD de /repo/. Préréglages de cache : paquets un an, icônes un jour, repo.xml 5 minutes et purgé à chaque publication, l'API, Forgejo et la connexion jamais mis en cache

Le nom d'hôte principal répond 404 à /ide/ tant qu'un administrateur n'active pas Publier l’éditeur. Le terminal de l'éditeur est un shell root sur le NAS : activez donc d'abord l'authentification à deux facteurs pour les comptes développeur et administrateur.
Tant que la CI est activée, un workflow poussé dans n'importe quel dépôt s'exécute en root sur le NAS, depuis Internet comme depuis le LAN. Ne donnez l'accès en push qu'aux personnes à qui vous confieriez le mot de passe administrateur du NAS.
Le premier mot de passe administrateur ne peut jamais être défini depuis un nom publié : l'écran de premier démarrage n'accepte qu'un client du réseau local.
Arrêter termine cloudflared et ne modifie rien chez Cloudflare. Retirer de Cloudflare supprime les enregistrements DNS, les règles de cache et le tunnel créés par le paquet, et oublie le jeton.