Costruisci Transmission da zero sul tuo NAS

Il video qui sotto è un'esecuzione reale di Bucket & Code Server IDE 1.0.0-55 su un NAS su cui non è ancora configurato nulla. Parte dalla schermata della prima esecuzione e finisce con il pacchetto QTS Transmission firmato, installato e raggiungibile dal browser, e con il download di una build arm_64 dello stesso pacchetto. Questa guida percorre il video capitolo per capitolo: cosa fa la persona, cosa mostra lo schermo e cosa controlla lo script.

1. Prepararemoduli, ambiente, runtime
2. ProgettoPacchetto dai sorgenti
3. Ricettecinque, il gate, il servizio
4. Compilaredue app, make qpkg
5. Installarefirma, deploy di prova, arm_64

Le immagini sono fotogrammi dell'esecuzione, dal pannello e dall'editor; solo i riquadri della Panoramica provengono dalla versione 1.0.0-62. L'indirizzo e il nome del NAS sono mascherati in ogni fotogramma e compaiono come nas.local e NAS.

01Cosa mostra il video, cosa ti serve

L'esecuzione è durata 25 min 7 s, il video dura 6:26. Il video taglia la parte centrale di ogni attesa più lunga di 10 secondi e indica sul taglio la durata reale dell'attesa. Ogni tratto di oltre 10 secondi senza clic scorre a velocità quadrupla, con il segno 4×.

Uno script pilota il browser: clicca nel pannello, digita ogni file del progetto finito nell'editor e controlla ogni passaggio tramite l'API del pannello prima di proseguire. Il pannello, l'editor, la compilazione e i pacchetti sono quelli veri. Il progetto finito è l'esempio Transmission (BitTorrent client, own recipes) sotto Progetti Editor nella scheda Esempi della pagina App; Vedi il codice ne mostra i file.

• Un NAS con Bucket & Code Server IDE 1.0.0-55 o successivo e un processore x86_64. Il pacchetto arm_64 è una compilazione incrociata fatta su quel NAS.
• Un account amministratore nel pannello. Su una nuova installazione lo crea la schermata della prima esecuzione.
• Accesso a Internet per il NAS: scarica il file system radice dell'ambiente di compilazione, le toolchain e i sorgenti delle ricette, e controlla ogni download con il suo sha256.
• Per il pacchetto firmato, un certificato per la firma del codice rilasciato a tuo nome da QNAP (sezione 07).

02Prima configurazione

Video 0:00 · nell'esecuzione 4 s

Una nuova installazione non ha account, quindi il pannello si apre su una sola schermata, Imposta la password dell’amministratore, per l'account administrator. Digita due volte una password di almeno 10 caratteri e premi Imposta la password e accedi. La schermata accetta la password per 60 minuti dopo l'avvio del pacchetto e solo dalla rete locale.

Lo script controlla che il pannello abbia effettuato l'accesso come administrator e non chieda più un primo amministratore.

03Moduli, ambiente, Go, Python e QDK

Video 0:06 · nell'esecuzione 59 s

La pagina Panoramica mostra ogni modulo come riquadro, e una nuova installazione esegue solo il nucleo. Attiva Git (Forgejo) e l'Editor (VS Code nel browser) con i loro interruttori finché entrambi i riquadri indicano in esecuzione. Ogni account del pannello ha un account Forgejo con lo stesso nome, quindi la procedura guidata del nuovo progetto ora propone administrator come proprietario di un repository.

Nella pagina Toolchain l'elenco degli ambienti è vuoto e offre il builder Ubuntu 24.04 con un solo pulsante, Crea questo ambiente. L'ambiente ubuntu2404-builder è pronto dopo 22 secondi. Nel catalogo sotto, Installa aggiunge Go 1.27 e Python 3.13 (scheda Runtime) e QNAP QDK 2.5.0 (scheda QNAP). Go compila il gate del progetto, Python esegue lo strumento che scrive l'elenco vendor dell'interfaccia web e QDK impacchetta i pacchetti QTS.

Lo script controlla che Git e l'Editor siano in esecuzione, che ubuntu2404-builder sia nell'elenco degli ambienti e che go-1.27-x86_64, python-3.13-x86_64 e qdk-2.5.0-x86_64 siano installati.

04Nuovo progetto

Video 0:52 · nell'esecuzione 24 s

Nella pagina Progetti, Nuovo progetto chiede prima il modello. Scegli Pacchetto dai sorgenti e chiama il progetto Transmission; il nome diventa il nome del pacchetto. Nel passaggio Servizio scegli App web: un servizio in background con la sua porta web e il pulsante Apri di App Center. Il passaggio Compilazione non chiede alcun ambiente: la riga ENV del Makefile del progetto assegna a entrambe le app il builder Ubuntu 24.04. Lascia disattivato Compila subito dopo la creazione, perché la ricetta iniziale indica ancora un sorgente segnaposto e una prima compilazione fallirebbe. Crea il progetto crea il repository Forgejo con il suo primo commit.

Apri nell’editor apre il progetto nell'editor. La sua cartella contiene recipes/transmission/ (la ricetta iniziale), recipes.txt, un Makefile per due app, licenses.txt, qpkg/ e scripts/. Lo script controlla che la pipeline del progetto elenchi le app transmission e transmission-arm64 e che Esplora risorse mostri recipes.

05Le ricette

Video 1:18 · nell'esecuzione 12 min 12 s

La libreria non ha una ricetta per Transmission né per la sua interfaccia web, quindi il progetto ne porta cinque proprie in recipes/, una cartella ciascuna con recipe.json e build.sh: queste due e libnatpmp, miniupnpc e libdeflate, che esistono anche nella libreria; nelle app del progetto le sue copie sostituiscono quelle della libreria. curl, OpenSSL, zlib e libevent arrivano dalla libreria. La tua prima ricetta spiega i due file.

La ricetta iniziale · 14 s

recipes/transmission/recipe.json riceve l'archivio della versione 4.1.3 di Transmission con il suo sha256, le ricette di cui ha bisogno (curl, OpenSSL, zlib, libevent, libnatpmp, miniupnpc e libdeflate), il collegamento statico e un controllo. build.sh esegue CMake per il daemon e per transmission-remote, transmission-create, transmission-edit e transmission-show, con test, traduzioni e documentazione disattivati.

Altre quattro ricette · 1 min 17 s

Nel riquadro comandi, Bucket: New recipe chiede un nome e scrive entrambi i file a partire dalla ricetta iniziale. Lo script crea in questo modo libnatpmp 20230423, miniupnpc 2.3.3, libdeflate 1.26 e transmission-web 4.1.3 e in ciascuna inserisce il sorgente, lo sha256 e i passaggi di compilazione. Transmission collega le tre librerie come archivi statici. L'interfaccia web è HTML, CSS e JavaScript, compilati da web/ dello stesso archivio della versione.

L'elenco vendor · 1 min 7 s

esbuild e Sass compilano l'interfaccia web, e recipes/transmission-web/vendor.txt fissa i loro pacchetti npm, una riga ciascuno con sha256, indirizzo e destinazione. Il terminale dell'editor scrive il file a partire dal package-lock.json della versione, e lo strumento riporta 30 files: 30 checked against the lockfile's sha512. Il file finito ha 41 righe, 11 delle quali sono commenti.

eval "$(bvs use python-3.13-x86_64)"
python3 /usr/bin/bucketvs/share/bucketvs/tools/npm-vendor.py package-lock.json CACHE-DIR \
  --dev --roots esbuild esbuild-sass-plugin fast-deep-equal \
  --platform linux-x64-glibc --platform linux-arm64-glibc --allow-install-scripts \
  > recipes/transmission-web/vendor.txt

build.sh contiene lo sha256 dell'intero file, e la compilazione controlla di nuovo ogni pacchetto prima di estrarlo. npm non viene mai eseguito, e nemmeno gli script di installazione.

L'elenco delle ricette, il gate, gli script, le licenze e le icone · 6 min 38 s

recipes.txt indica ciò che compilano le due app: transmission, transmission-web e cacert, il bundle di certificati CA con cui curl controlla i tracker HTTPS. App Builder aggiunge ciò che serve a ciascuna.

gate/ contiene trgate, un programma Go senza moduli esterni. Le impostazioni predefinite di Transmission non hanno password e accettano chiamate RPC solo dal NAS stesso; aperto alla rete senza password, servirebbe chiunque raggiunga la porta 9091. Perciò il pacchetto avvia transmission-daemon solo dopo che hai scelto una password: trgate occupa la porta con una pagina di configurazione, scrive la password nella forma con salt in cui la memorizza Transmission e poi avvia il daemon sulla stessa porta. Il pacchetto non genera alcuna password, quindi nessuna viene scritta in un file né nei log di sistema di QTS.

scripts/make-qpkg.sh è il packer del modello con tre punti compilati: KEEP, i percorsi che il pacchetto prende da ogni app; own_programs, che compila trgate per ogni architettura; e own_licences, che aggiunge i testi di licenza che licenses.txt non può fornire. licenses.txt elenca la licenza di ogni ricetta contenuta nel pacchetto, e LICENSE è la licenza del codice proprio del progetto. Lo script digita questi dieci file. Le tre icone di qpkg/icons/ si caricano con Upload... su quella cartella in Esplora risorse.

Il servizio · 40 s

Nella vista del progetto, la scheda Servizio e pacchetto contiene i blocchi che scrivono lo script di avvio e arresto del pacchetto e le chiavi di qpkg.cfg. Partendo dal preset App web, lo script arriva a nove blocchi: la cartella dati Transmission sul volume; l'account transmission nel gruppo arr, proprietario di quella cartella (modalità 700); la porta web 9091; trgate come daemon dell'account, con 40 secondi per arrestarsi; un'attesa della porta 9091; una riga di log; e i controlli di stato running e port_open. La scheda Pacchetto imposta il nome visualizzato Transmission, la versione 4.1.3, il percorso della pagina web /transmission/web/, la porta web 9091 e 60 secondi di attesa di QTS all'avvio e all'arresto. Salva mostra il piano con il diff di ogni file, e Esegui il commit lo registra.

Il controllo · 30 s

A ogni salvataggio vengono controllate le ricette del progetto, e i rilievi compaiono nella vista Problemi. Lo script attende No problems have been detected in the workspace, e il rapporto del progetto elenca allora cinque ricette e nessun errore. make lint mostra gli stessi rilievi nel terminale.

Commit e push · 1 min 42 s

In Controllo del codice sorgente lo script prepara tutte le modifiche, le registra come Transmission from source e le invia con push. Il repository remoto del progetto è il suo repository Forgejo via HTTPS, quindi l'editor chiede nome e password dell'account, che Forgejo condivide con il pannello. Lo script attende che non resti nulla da registrare né da inviare al remoto, poi rilegge le tre icone da Forgejo e le confronta byte per byte con quelle del progetto.

06Compilazione e make qpkg

Video 5:13 · nell'esecuzione 10 min 1 s

Compila nella vista del progetto esegue il Makefile del progetto. Compila le due app una dopo l'altra nel builder Ubuntu 24.04, entrambe statiche: transmission per il processore x86_64 di questo NAS e transmission-arm64 per aarch64, come compilazione incrociata. Ogni app compila 13 ricette in ordine di dipendenza: cacert, OpenSSL, zlib, nghttp2, zstd, c-ares, curl e libevent dalla libreria, poi libnatpmp, miniupnpc, libdeflate, transmission e transmission-web dal progetto. Ci sono voluti 8 min 1 s. I controlli della compilazione incrociata girano solo dove qemu-user è registrato; altrove la compilazione li registra come non eseguiti. Lo script controlla che le ultime compilazioni di entrambe le app siano concluse e indichino il progetto Transmission.

I pacchetti si creano nel terminale dell'editor, nella cartella del progetto (2 min 0 s). Go deve essere nel PATH, perché make qpkg compila trgate per ogni architettura:

eval "$(bvs use go-1.27-x86_64)"
make qpkg

make qpkg impacchetta con QDK l'ultima compilazione riuscita di ogni app e scrive Transmission_4.1.3_x86_64.qpkg e Transmission_4.1.3_arm_64.qpkg in build/qpkg/build/, circa 30 MB ciascuno. Un pacchetto contiene i cinque programmi di Transmission, trgate, l'interfaccia web, il bundle di certificati CA, il BusyBox che la compilazione aggiunge a ogni pacchetto e share/licenses/ con un NOTICE e i testi di licenza di ogni componente.

07La firma

Non nel video · nell'esecuzione 3 s

È l'unico passaggio fuori dal pannello. Il deploy di prova installa solo pacchetti firmati e non salta mai il controllo della firma di App Center, e il NAS dell'esecuzione non ha file per la firma del codice, quindi make qpkg ha compilato entrambi i pacchetti senza firma. Lo script li copia su un computer che ha un certificato per la firma del codice rilasciato da QNAP all'autore di questa guida, li firma lì con qbuild di QDK, controlla le firme e copia i pacchetti di nuovo in build/qpkg/build/. Il certificato e la sua chiave privata non vanno mai sul NAS. L'elenco Versioni segna poi entrambi i pacchetti come firmati.

Firmi con un certificato tuo. Metti certificate e private_key, e ca_certs per la catena, accanto a qpkg/qpkg.cfg o nella cartella indicata da QPKG_CERT_DIR, e make qpkg firma da sé i pacchetti; il .gitignore del modello tiene i file fuori da git. Senza di essi i pacchetti non sono firmati e il deploy di prova li rifiuta. Che cosa fa un NAS con un pacchetto non firmato lo decide il suo proprietario in App Center; questa guida sconsiglia di installare pacchetti non firmati.

08Deploy di prova e primo accesso

Video 5:53 · nell'esecuzione 32 s

Nella pagina del progetto, Deploy di prova (riservato agli amministratori) installa il pacchetto x86_64 su questo NAS con qpkg_cli, come App Center installa un file, e il job attende la conferma di App Center. Il pacchetto resta installato finché non lo rimuovi con Rimuovi da questo NAS o in App Center. Il job è durato 18 s.

Apri http://<NAS>:9091/ oppure premi Apri in App Center. La pagina del gate, Choose the web interface password, chiede un nome utente (admin se non lo cambi) e due volte la password, di almeno 8 caratteri. Premi Start Transmission. La pagina dice che Transmission si sta avviando, poi transmission-daemon prende la porta e il browser chiede il nome utente e la password che hai scelto. La pagina accetta questi dati solo nei 60 minuti dopo l'avvio del pacchetto, da un computer della rete del NAS, aperta con l'indirizzo IP del NAS o con il suo nome.

Dopo l'accesso, il browser mostra l'interfaccia web di Transmission senza trasferimenti. Lo script controlla che il titolo della pagina sia Transmission Web Interface e che l'RPC riporti la versione 4.1.3 (838877323f).

09Il pacchetto arm_64

Video 6:20 · nell'esecuzione 23 s

Un clic destro sulla riga arm_64 dell'elenco Versioni apre il suo menu, e Scarica salva Transmission_4.1.3_arm_64.qpkg (30.290.058 byte). Lo script confronta la dimensione del file con quella dell'elenco.

Un NAS x86_64 non può eseguire quel pacchetto, quindi lo script lo controlla in emulazione. scripts/qemu-test.sh decomprime il download su un computer Linux in cui qemu-user è registrato e lo esegue lì. Tutti i 22 controlli passano in 19 s:

• i programmi sono eseguibili AArch64 statici, e BusyBox e transmission-daemon partono;
• il gate serve la pagina di impostazione, transmission-daemon non gira prima che la password sia impostata e un POST senza l'header della pagina viene rifiutato (403);
• dopo l'impostazione l'RPC risponde, session-get riporta la versione 4.1.3, una password errata viene rifiutata (401), l'interfaccia web risponde e né l'output né settings.json contengono la password;
• transmission-daemon scarica via HTTPS il .torrent netinst di Debian, il che richiede il bundle di certificati CA del pacchetto, e il torrent viene poi rimosso;
• un TERM inviato al gate termina transmission-daemon e il gate termina con codice 0.

In questa esecuzione nessun NAS ARM ha eseguito il pacchetto.

10Guide correlate

• La tua prima ricetta percorre la ricetta iniziale, il controllo e make qpkg con un piccolo programma, cmatrix.
• Un'app personalizzata dalle tue ricette crea un'app di App Builder che usa le ricette di un progetto oltre a quelle della libreria.
• Transmission in App Center è l'esempio pubblicato. Il suo pacchetto x86_64 viene da un'esecuzione precedente dello stesso script su 1.0.0-55; il suo SHA-256 è in quella pagina.
• La guida per l'utente di Bucket & Code Server IDE descrive Nuovo progetto, la vista del progetto, Toolchain, App Builder e la firma del codice di un pacchetto.