Il tuo App Center: distribuisci i pacchetti QPKG da Git a ogni NAS

Bucket & Code Server IDE mantiene un repository App Center sul tuo NAS. Un progetto QPKG creato con Nuovo progetto viene compilato a ogni push su Git e vi pubblica il pacchetto firmato. Gli altri NAS aggiungono una volta l'indirizzo del repository in App Center, poi installano e aggiornano i tuoi pacchetti come qualsiasi altra app. Cloudflare Tunnel rende raggiungibili su internet il repository, e Git se lo desideri, senza aprire una porta del router.

1. Preparamoduli, QDK, un certificato
2. ProgettoNuovo progetto, pacchetto QPKG
3. Firmadue segreti in Forgejo
4. Repositoryil suo indirizzo in App Center
5. Internetun nome host dei pacchetti

Le immagini provengono dal pannello, con ogni campo compilato come descritto in questa guida. Gli indirizzi sono quelli di un NAS con IP 192.168.1.20, e i nomi pubblicati sono esempi sotto example.com.

01Prima di iniziare

• Git, CI e l'Editor devono essere attivi: un amministratore li attiva con il rispettivo pulsante nella Panoramica (Attiva Git, Attiva Git e CI, Attiva Editor). La procedura guidata Nuovo progetto richiede Git e l'Editor, e CI esegue il flusso di lavoro del progetto a ogni push.
• QDK deve essere installato: nella pagina Toolchain, scheda QNAP, installa QNAP QDK 2.5.0.
• Ti serve un certificato di firma del codice rilasciato da QNAP, in forma di file: certificate, private_key e, per la catena, ca_certs. App Center verifica la firma del codice di un pacchetto al momento dell'installazione, e il repository nella pagina Pacchetti accetta solo pacchetti con firma del codice. Un certificato su token hardware non è supportato.

02Crea il progetto

Apri Nuovo progetto dalla pagina Git o dalla palette dei comandi (ruolo sviluppatore).

1. Modello. In Pacchetti per QTS scegli Pacchetto QPKG e premi Avanti.
2. Nome e visibilità. Il nome è quello del repository, della cartella e del pacchetto: da 1 a 20 lettere, cifre, trattini o trattini bassi. Il proprietario è il tuo account o un'organizzazione; lascia il progetto Privato.
3. Servizio. Scegli come il pacchetto si avvia e si ferma: Strumento da riga di comando collega il programma in /usr/bin, Servizio in background lo esegue con un account tutto suo, App web aggiunge anche il pulsante Apri di App Center, e Vuota contiene solo i comandi di base del servizio (start, stop e così via). Puoi cambiare questi blocchi in seguito nella vista Progetto.
4. Compilazione. Scegli l'ambiente in cui il progetto viene compilato e lascia attivo Compila subito dopo la creazione.
5. Pubblicazione. Attiva Pubblica nel repository di App Center di questo NAS. Lo stesso interruttore resta poi nelle impostazioni del progetto e permette alla CI di pubblicare a ogni esecuzione.
6. Revisione. Controlla i passaggi che verranno eseguiti e premi Crea il progetto.

Il primo job crea il repository in Forgejo e la cartella projects/<name> con il primo commit: i file del modello e il flusso di lavoro .forgejo/workflows/build.yml. La prima build non ha ancora un certificato, quindi il passaggio di pubblicazione si ferma e segnala che il pacchetto non ha firma del codice. L'interruttore resta attivo e, completato il passaggio 03, ogni push pubblica il pacchetto.

03Firma ogni build

Sul NAS, metti i file del certificato accanto a qpkg.cfg nella cartella projects/<name>. Il file .gitignore del modello li esclude da git. Una build in quella cartella firma allora il pacchetto, e la prima riga di bvs qbuild riporta case 1. Se nell'ambiente mancano openssl o bsdextrautils, la build si ferma e indica il comando che li aggiunge.

CI esegue il checkout del repository senza quei file, quindi li ottiene da due segreti. In Forgejo apri Impostazioni → Azioni → Segreti del repository e premi due volte Aggiungi segreto: QPKG_CERTIFICATE con l'output di base64 -w0 certificate, e QPKG_PRIVATE_KEY con quello di base64 -w0 private_key. È Forgejo stesso a chiedere Base64 quando un valore deve conservare i suoi a capo. Un certificato con catena richiede un terzo segreto, QPKG_CA_CERTS, e una terza riga nel primo passaggio che lo scrive in ca_certs.

Poi aggiungi due passaggi a .forgejo/workflows/build.yml: uno che scrive i file prima della build, subito dopo il checkout, e uno alla fine dell'elenco che li rimuove qualunque sia il risultato. I passaggi propri del modello restano invariati.

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

04Ogni push pubblica

Ogni push nel repository esegue il workflow sul runner del NAS stesso. Il workflow compila il pacchetto e lo pubblica con --latest, così repo.xml elenca subito la nuova versione e App Center la propone al suo prossimo controllo. Una build non firmata non viene pubblicata: l'esecuzione termina con un avviso che ne indica il motivo.

La pagina del progetto (Progetti, o la barra laterale dell'Editor) permette di eseguire gli stessi passaggi a mano: Compila, Ricompila, Deploy di prova (solo per un amministratore, solo pacchetti firmati) e Pubblica.

La scheda Impostazioni contiene l'interruttore Pubblica nel repository di App Center. Finché è disattivato, un'esecuzione di CI salta la pubblicazione con un avviso.

La pagina Pacchetti elenca ogni pacchetto con l'ultima versione e la firma. Una versione che uno sviluppatore carica lì a mano attende finché un amministratore non la rende l'ultima.

05Aggiungi il repository sulle altre unità NAS

1. Copia l'indirizzo dalla scheda Indirizzo per App Center nella pagina Pacchetti.
2. Sull'altro NAS: App Center → ⚙ Settings → App Repository → Aggiungi. Assegna un nome, incolla l'indirizzo e premi Aggiungi.
3. I tuoi pacchetti si trovano sotto quel nome nella barra laterale sinistra di App Center. Installali da lì. Quando il repository elenca una versione più recente, App Center la propone come aggiornamento.

Questo indirizzo LAN funziona per le unità NAS della tua rete. Per un NAS fuori dalla tua rete, pubblica il repository su internet.

06Su internet con Cloudflare Tunnel

Il pacchetto include cloudflared, che si connette in uscita dal NAS verso Cloudflare: non si apre alcuna porta del router, e Cloudflare gestisce i certificati per i nomi. Ti serve un dominio il cui DNS sia gestito da Cloudflare e un token API per quella zona (dash.cloudflare.com, My Profile → API Tokens) con quattro permessi: Account, Cloudflare Tunnel, Edit; Zone, DNS, Edit; Zone, Cache Rules, Edit; Zone, Cache Purge, Purge. Se il token usa il Client IP Address Filtering, inserisci nel filtro entrambi gli indirizzi pubblici del NAS, IPv4 e IPv6.

1. Per un nome host principale, attiva prima Navigazione pubblica nella pagina Git e premi Salva e riavvia Forgejo: la pagina Pubblicazione rifiuta un nome host principale finché l'opzione è disattivata. I repository contrassegnati come privati restano nascosti.
2. Apri Pubblicazione in Amministrazione (solo amministratori). Digita i nomi e il token, lascia attivo Preimpostazioni di cache e premi Pubblica. Il pacchetto controlla prima tutto su Cloudflare; se un controllo fallisce, lì non cambia nulla e ti dice cosa correggere.
3. Poi crea il tunnel, fa puntare ogni nome al tunnel e avvia cloudflared. La scheda Tunnel mostra le connessioni.
4. Ora l'indirizzo per App Center nella pagina Pacchetti contiene il nome host dei pacchetti. Aggiungi quell'indirizzo sulle unità NAS fuori dalla tua rete.
5. Con un nome host principale, imposta URL pubblico nella pagina Rete sul suo indirizzo, così i link di Forgejo e gli indirizzi di clonazione HTTPS lo usano.

• Git via SSH non passa dal tunnel. Dall'esterno, clona e fai push via HTTPS, oppure inoltra una porta del router alla porta di Git via SSH (9952) e imposta Host SSH negli URL di clonazione nella pagina Rete.
• Cloudflare accetta richieste fino a 100 MB. Per push o caricamenti più grandi usa l'indirizzo LAN.
• Una pubblicazione nel repository rimuove subito repo.xml dalla cache di Cloudflare, così App Center vede la nuova versione al suo prossimo controllo.

07Cosa raggiunge internet

La pagina Pubblicazione elenca a cosa dà accesso ogni nome, con accanto le regole di cache.

• Il nome host principale risponde a /ide/ con 404 finché un amministratore non attiva Pubblica l’editor. Il terminale dell'editor è una shell root sul NAS, quindi attiva prima l'autenticazione a due fattori per gli account di sviluppatore e amministratore.
• Finché la CI è attiva, un workflow inviato con push a qualsiasi repository viene eseguito come root sul NAS, che arrivi da internet o dalla LAN. Concedi l'accesso in push solo a persone a cui affideresti la password admin del NAS.
• La prima password dell'amministratore non viene mai impostata tramite un nome pubblicato: la schermata di primo avvio accetta solo un client sulla rete locale.
• Ferma termina cloudflared e non modifica nulla su Cloudflare. Rimuovi da Cloudflare elimina i record DNS, le regole di cache e il tunnel creati dal pacchetto, ed elimina il token salvato.