Vlastní App Center: posílejte balíčky QPKG z Gitu na každé NAS

Bucket & Code Server IDE udržuje na vašem NAS repozitář App Center. QPKG projekt vytvořený tlačítkem New project se sestaví při každém pushi do Gitu a podepsaný balíček do něj publikuje. Vaše ostatní NAS přidají adresu repozitáře v App Center jednou a poté instalují a aktualizují balíčky jako jakoukoli jinou aplikaci. Cloudflare Tunnel zpřístupní repozitář, případně i Git, na internetu bez otevření portu na routeru.

1. Přípravamoduly, QDK, certifikát
2. ProjektNew project, QPKG package
3. Podpisdva tajné klíče ve Forgejo
4. Repozitářjeho adresa v App Center
5. Internetnázev hostitele pro balíčky

Snímky pocházejí z panelu, ve kterém je každé pole vyplněné podle tohoto návodu. Adresy patří NASu na adrese 192.168.1.20 a zveřejněné názvy jsou příklady v doméně example.com.

01Než začnete

• Git, CI a Editor musí být zapnuté: administrátor každý z nich zapne jeho tlačítkem na stránce Overview (Turn on Git, Turn on Git and CI, Turn on Editor). Průvodce New project potřebuje Git a Editor a CI spouští pracovní postup projektu při každém pushi.
• QDK musí být nainstalovaný: na stránce Toolchains, na záložce QNAP, nainstalujte QNAP QDK 2.5.0.
• Potřebujete certifikát pro podepisování kódu, který vám vydal QNAP, ve formě souborů: certificate, private_key a pro řetězec ca_certs. App Center při instalaci balíčku kontroluje jeho podpis kódu a repozitář na stránce Packages přijímá pouze balíčky podepsané kódem. Certifikát na hardwarovém tokenu není podporován.

02Vytvoření projektu

Otevřete New project na stránce Git nebo z palety příkazů (role developer).

1. Šablona. V sekci Packages for QTS zvolte QPKG package a stiskněte Next.
2. Název a viditelnost. Stejný název dostane repozitář, složka i balíček: 1 až 20 písmen, číslic, pomlček nebo podtržítek. Vlastníkem je váš účet nebo organizace; projekt ponechte jako Private.
3. Služba. Zvolte, jak balíček startuje a zastavuje: Command-line tool připojí program do /usr/bin, Background service ho spouští pod vlastním účtem, Web app mu navíc přidá tlačítko Open z App Center a Empty má jen holé příkazy služby (start, stop a podobně). Tyto bloky můžete později změnit v pohledu Project.
4. Sestavení. Vyberte prostředí, ve kterém se projekt sestavuje, a ponechte zapnuté Build right after creating.
5. Publikování. Zapněte Publish to this NAS’s App Center repository. Stejný přepínač pak zůstane v nastavení projektu a umožní CI publikovat při každém běhu.
6. Kontrola. Zkontrolujte kroky, které se spustí, a stiskněte Create project.

První úloha vytvoří repozitář ve Forgejo a složku projects/<name> s prvním commitem: soubory šablony a pracovní postup .forgejo/workflows/build.yml. První sestavení zatím nemá certifikát, takže se jeho krok publikace zastaví a ohlásí, že balíček nenese podpis kódu. Přepínač zůstane zapnutý, a jakmile dokončíte krok 03, každý push balíček publikuje.

03Podepište každé sestavení

Na NASu uložte soubory certifikátu vedle qpkg.cfg ve složce projects/<name>. .gitignore šablony je drží mimo git. Sestavení v této složce pak balíček podepíše a první řádek bvs qbuild hlásí case 1. Pokud prostředí postrádá openssl nebo bsdextrautils, sestavení se zastaví a uvede příkaz, který je doplní.

CI si repozitář stáhne (checkout) bez těchto souborů, a proto je získá ze dvou tajných klíčů. Ve Forgejo otevřete Settings → Actions → Secrets repozitáře a dvakrát stiskněte Add secret: QPKG_CERTIFICATE s výstupem příkazu base64 -w0 certificate a QPKG_PRIVATE_KEY s výstupem příkazu base64 -w0 private_key. Base64 vyžaduje samo Forgejo, když se mají v hodnotě zachovat zalomení řádků. Certifikát s řetězcem potřebuje třetí tajný klíč, QPKG_CA_CERTS, a třetí řádek v prvním kroku, který jej zapíše do ca_certs.

Pak přidejte do .forgejo/workflows/build.yml dva kroky: jeden, který zapíše soubory před sestavením hned po checkoutu, a jeden na konci seznamu, který je odstraní bez ohledu na výsledek. Vlastní kroky šablony zůstanou beze změny.

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

04Každé odeslání publikuje

Každé odeslání do repozitáře spustí workflow na vlastním runneru NAS. Sestaví balíček a publikuje ho s --latest, takže repo.xml hned uvádí novou verzi a App Center ji nabídne při další kontrole. Nepodepsaný balíček se nepublikuje: běh skončí varováním, které uvádí důvod.

Stránka projektu (Projects, nebo postranní panel Editoru) spouští tytéž kroky ručně: Build, Rebuild, Test deploy (jen pro administrátora, jen podepsané balíčky) a Publish.

Karta Settings projektu obsahuje přepínač Publish to the App Center repository. Dokud je vypnutý, běh CI publikaci přeskočí s upozorněním.

Stránka Packages vypisuje každý balíček s nejnovější verzí a podpisem. Verze, kterou tam vývojář nahraje ručně, čeká, dokud ji administrátor nenastaví jako nejnovější.

05Přidejte repozitář na další jednotky NAS

1. Zkopírujte adresu z karty App Center address na stránce Packages.
2. Na druhém NASu: App Center → ⚙ Settings → App Repository → Add. Zadejte název, vložte adresu a stiskněte Add.
3. Vaše balíčky jsou pod tímto názvem v levém panelu App Center. Nainstalujte je tam. Když repozitář uvede novější verzi, App Center ji nabídne jako aktualizaci.

Tato adresa v LAN funguje pro jednotky NAS ve vaší síti. Pro jednotku mimo ni zpřístupněte repozitář na internetu.

06Přes internet pomocí Cloudflare Tunnel

Balíček obsahuje cloudflared, který se z NASu připojuje ven ke Cloudflare: žádný port na routeru se neotevírá a certifikáty pro názvy drží Cloudflare. Potřebujete doménu, jejíž DNS je u Cloudflare, a API token pro tuto zónu (dash.cloudflare.com, My Profile → API Tokens) se čtyřmi oprávněními: Account, Cloudflare Tunnel, Edit; Zone, DNS, Edit; Zone, Cache Rules, Edit; Zone, Cache Purge, Purge. Pokud token obsahuje Client IP Address Filtering, vložte do něj obě veřejné adresy NASu, IPv4 i IPv6.

1. U hlavního názvu hostitele nejdřív na stránce Git zapněte Public browsing a stiskněte Save and restart Forgejo: stránka Publish bez toho hlavní název hostitele odmítne. Repozitáře označené jako soukromé zůstanou skryté.
2. Otevřete Publish v sekci Administration (jen administrátoři). Zadejte názvy a token, nechte zapnuté Cache presets a stiskněte Publish. Balíček nejdřív všechno ověří u Cloudflare. Když některá kontrola selže, nic tam nezmění a řekne, co je třeba opravit.
3. Pak vytvoří tunel, nasměruje na něj každý název a spustí cloudflared. Karta Tunnel ukazuje spojení.
4. Adresa App Center na stránce Packages nyní ukazuje na název hostitele pro balíčky. Tuto adresu přidejte na jednotky NAS mimo vaši síť.
5. U hlavního názvu hostitele nastavte na stránce Network položku Public URL na jeho adresu, aby ji používaly odkazy Forgejo i adresy pro klonování přes HTTPS.

• Git přes SSH tunel neprochází. Zvenku klonujte a posílejte přes HTTPS, nebo přesměrujte port na routeru na port Git přes SSH (9952) a na stránce Network nastavte SSH host in clone URLs.
• Cloudflare přijímá požadavky do 100 MB. Větší soubory odesílejte nebo nahrávejte přes adresu v LAN.
• Publikace do repozitáře okamžitě smaže repo.xml z cache Cloudflare, takže App Center uvidí novou verzi při další kontrole.

07Co je dostupné z internetu

Stránka Publish vypisuje, co každý název obsluhuje, a vedle toho pravidla cache.

• Hlavní název hostitele odpovídá na /ide/ chybou 404, dokud administrátor nezapne Publish the editor. Terminál editoru je root shell na NASu, proto nejdřív zapněte dvoufaktorové ověření pro účty vývojářů a administrátorů.
• Dokud je CI zapnuté, každý workflow, který někdo pošle do kteréhokoli repozitáře, běží na NASu jako root, ať přišel z internetu, nebo z LAN. Přístup pro push dávejte jen lidem, kterým byste svěřili heslo administrátora NASu.
• Heslo prvního administrátora se nikdy nenastavuje přes publikovaný název: obrazovka prvního spuštění přijme jen klienta v místní síti.
• Stop ukončí cloudflared a na straně Cloudflare nic nezmění. Remove from Cloudflare smaže DNS záznamy, pravidla cache a tunel, které balíček vytvořil, a zapomene token.