Je eigen App Center: lever je QPKG-pakketten vanaf Git naar elke NAS

Bucket & Code Server IDE houdt een App Center-repository op je NAS bij. Een QPKG-project dat je aanmaakt met Nieuw project bouwt bij elke Git-push en publiceert het ondertekende pakket daarin. Je andere NAS-apparaten voegen het adres van de repository eenmalig toe in App Center en kunnen daarna je pakketten installeren en bijwerken, net als elke andere app. Cloudflare Tunnel kan de repository, en desgewenst ook Git, op internet publiceren zonder dat je een poort op de router opent.

1. Voorbereidenmodules, QDK, een certificaat
2. ProjectNieuw project, QPKG-pakket
3. Ondertekenentwee geheimen in Forgejo
4. Repositoryhet adres ervan in App Center
5. Interneteen hostnaam voor pakketten

De afbeeldingen komen uit het paneel, met elk veld ingevuld zoals deze handleiding beschrijft. De adressen zijn die van een NAS op 192.168.1.20, en de gepubliceerde namen zijn voorbeelden onder example.com.

01Voordat je begint

• Git, CI en de Editor moeten aan staan: een beheerder zet elke module aan met de knop op het Overzicht (Git aanzetten, Git en CI aanzetten, Editor aanzetten). De wizard Nieuw project heeft Git en de Editor nodig, en CI voert bij elke push de workflow van het project uit.
• QDK moet geïnstalleerd zijn: installeer op de pagina Toolchains, tabblad QNAP, QNAP QDK 2.5.0.
• Je hebt een certificaat voor codeondertekening nodig dat QNAP aan jou heeft uitgegeven, in de vorm van bestanden: certificate, private_key en, voor de keten, ca_certs. App Center controleert de codehandtekening van een pakket bij de installatie, en de repository op de pagina Pakketten accepteert alleen pakketten met codeondertekening. Een certificaat op een hardwaretoken wordt niet ondersteund.

02Het project aanmaken

Open Nieuw project op de pagina Git of via het opdrachtenpalet (rol developer).

1. Sjabloon. Kies onder Pakketten voor QTS de optie QPKG-pakket en druk op Volgende.
2. Naam en zichtbaarheid. De naam is die van de repository, de map en het pakket: 1 tot 20 letters, cijfers, koppeltekens of underscores. De eigenaar is je account of een organisatie; laat het project op Privé staan.
3. Dienst. Kies hoe het pakket start en stopt: Opdrachtregelprogramma koppelt het programma in /usr/bin, Achtergronddienst draait het onder een eigen account, Webapp geeft het daarnaast de knop Openen van App Center, en Leeg bevat alleen de kale dienstopdrachten (start, stop enzovoort). Deze blokken kun je later aanpassen in de weergave Project.
4. Bouwen. Kies de omgeving waarin het project bouwt en laat Direct na het aanmaken bouwen aan staan.
5. Publiceren. Zet Publiceren in de App Center-repository van deze NAS aan. Dezelfde schakelaar blijft daarna in de instellingen van het project staan en laat CI bij elke run publiceren.
6. Controle. Bekijk de stappen die worden uitgevoerd en druk op Project aanmaken.

De eerste taak maakt de repository in Forgejo aan, en de map projects/<name> met de eerste commit: de bestanden van het sjabloon en de workflow .forgejo/workflows/build.yml. Bij de eerste build is er nog geen certificaat, dus de publicatiestap stopt en meldt dat het pakket geen codehandtekening heeft. De schakelaar blijft aan, en zodra stap 03 klaar is, publiceert elke push.

03Elke build ondertekenen

Zet op de NAS de bestanden van het certificaat naast qpkg.cfg in projects/<name>. Het .gitignore van het sjabloon houdt ze buiten git. Een build in die map ondertekent dan het pakket, en de eerste regel van bvs qbuild zegt case 1. Als de omgeving openssl of bsdextrautils mist, stopt de build en noemt hij de opdracht die ze installeert.

CI checkt de repository uit zonder die bestanden en haalt ze daarom uit twee geheimen. Open in Forgejo bij de repository Instellingen → Acties → Geheimen en druk twee keer op Geheim toevoegen: QPKG_CERTIFICATE met de uitvoer van base64 -w0 certificate, en QPKG_PRIVATE_KEY met die van base64 -w0 private_key. Forgejo vraagt zelf om Base64 wanneer de regeleinden van een waarde behouden moeten blijven. Een certificaat met keten heeft een derde geheim nodig, QPKG_CA_CERTS, en een derde regel in de eerste stap die het naar ca_certs schrijft.

Voeg daarna twee stappen toe aan .forgejo/workflows/build.yml: een die de bestanden schrijft vóór de build, direct na de checkout, en een aan het eind van de lijst die ze verwijdert, ongeacht het resultaat. De eigen stappen van het sjabloon blijven zoals ze zijn.

# .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

04Elke push publiceert

Bij elke push naar de repository draait de workflow op de eigen runner van de NAS. De workflow bouwt het pakket en publiceert het met --latest, zodat repo.xml de nieuwe versie meteen vermeldt en App Center die bij de volgende controle aanbiedt. Een ongetekende build wordt niet gepubliceerd: de run eindigt met een waarschuwing die de reden noemt.

De pagina van het project (Projecten, of de zijbalk van de Editor) voert dezelfde stappen met de hand uit: Bouwen, Opnieuw bouwen, Testuitrol (alleen van een beheerder, alleen ondertekende pakketten) en Publiceren.

De kaart Instellingen bevat de schakelaar Publiceren in de App Center-repository. Zolang die uit staat, slaat een CI-run de publicatie over met een melding.

De pagina Pakketten toont elk pakket met de nieuwste versie en de handtekening. Een versie die een developer daar met de hand uploadt, wordt pas de nieuwste als een beheerder dat zo instelt.

05Voeg de repository toe op je andere NAS-apparaten

1. Kopieer het adres van de kaart App Center-adres op de pagina Pakketten.
2. Op de andere NAS: App Center → ⚙ Instellingen → App-repository → Toevoegen. Geef de repository een naam, plak het adres en druk op Toevoegen.
3. Je pakketten staan onder die naam in de linkerkolom van App Center. Installeer ze daar. Zodra de repository een nieuwere versie vermeldt, biedt App Center die aan als update.

Dit LAN-adres werkt voor NAS-apparaten in je netwerk. Voor een NAS buiten je netwerk publiceer je de repository op internet.

06Via internet met Cloudflare Tunnel

Het pakket bevat cloudflared, dat vanaf de NAS een uitgaande verbinding met Cloudflare maakt: er hoeft geen poort op de router open, en Cloudflare beheert de certificaten voor de namen. Je hebt een domein nodig waarvan de DNS bij Cloudflare staat, en een API-token voor die zone (dash.cloudflare.com, My Profile → API Tokens) met vier rechten: Account, Cloudflare Tunnel, Edit; Zone, DNS, Edit; Zone, Cache Rules, Edit; Zone, Cache Purge, Purge. Heeft het token Client IP Address Filtering, zet dan beide publieke adressen van de NAS erin, IPv4 en IPv6.

1. Bij een hoofdhostnaam moet je eerst Openbaar bladeren inschakelen op de pagina Git en op Opslaan en Forgejo herstarten drukken: de pagina Publiceren weigert een hoofdhostnaam zolang dit uit staat. Repositories die als privé zijn gemarkeerd, blijven verborgen.
2. Open Publiceren onder Beheer (alleen beheerders). Typ de namen en het token, laat Cache-voorinstellingen aan staan en druk op Publiceren. Het pakket controleert alles eerst bij Cloudflare, verandert daar niets als een controle mislukt, en vertelt wat je moet oplossen.
3. Daarna maakt het pakket de tunnel aan, laat elke naam ernaar wijzen en start cloudflared. De kaart Tunnel toont de verbindingen.
4. Het App Center-adres op de pagina Pakketten noemt nu de hostnaam voor pakketten. Voeg dat adres toe op NAS-apparaten buiten je netwerk.
5. Bij een hoofdhostnaam stel je Openbare URL op de pagina Netwerk in op het adres ervan, zodat de links van Forgejo en de HTTPS-kloonadressen dat adres gebruiken.

• Git via SSH gaat niet via de tunnel. Van buitenaf kloon en push je via HTTPS, of je stuurt een poort op de router door naar de Git-over-SSH-poort (9952) en stelt op de pagina Netwerk SSH-host in kloon-URL’s in.
• Cloudflare accepteert verzoeken tot 100 MB. Push of upload alles wat groter is via het LAN-adres.
• Een publicatie naar de repository wist repo.xml meteen uit de cache van Cloudflare, zodat App Center de nieuwe versie bij de volgende controle ziet.

07Wat het internet bereikt

De pagina Publiceren toont wat elke naam levert, en de cacheregels ernaast.

• De hoofdhostnaam antwoordt op /ide/ met 404 totdat een beheerder De editor publiceren inschakelt. De terminal van de editor is een root-shell op de NAS, dus schakel eerst tweefactorauthenticatie in voor developer- en beheerdersaccounts.
• Zolang CI aan staat, draait elke workflow die naar een repository wordt gepusht als root op de NAS, of de push nu van internet komt of van het LAN. Geef pushtoegang alleen aan mensen aan wie je ook het beheerderswachtwoord van de NAS zou geven.
• Het eerste beheerderswachtwoord wordt nooit via een gepubliceerde naam ingesteld: het scherm bij de eerste start accepteert alleen een client op het lokale netwerk.
• Stoppen beëindigt cloudflared en verandert niets bij Cloudflare. Van Cloudflare verwijderen verwijdert de DNS-records, de cacheregels en de tunnel die het pakket heeft gemaakt, en vergeet het token.