"title":"Installare un’immagine non presente nel catalogo | ProxMenux",
"description":"Adatta un’immagine OCI da un file Compose, un URL, un comando docker run o un riferimento all’immagine e verifica cosa può riprodurre ProxMenux prima di installarla."
},
"header":{
"title":"Installa un’immagine non presente nel catalogo",
"description":"L’immagine viene adattata dal suo file Compose, da un comando docker run o dal solo riferimento. Il risultato viene mostrato per la revisione prima di creare qualsiasi LXC.",
"section":"OCI manager Apps"
},
"sections":[
{
"id":"intro",
"blocks":[
{
"calloutInfo":{
"title":"Lo stesso convertitore e lo stesso installer",
"body":"L’opzione <strong>Installa un’immagine non presente nel catalogo</strong> usa il convertitore e l’installer dei modelli del catalogo. La differenza è che il contratto viene generato al momento dalla definizione fornita e verificato prima di creare qualsiasi LXC."
}
}
]
},
{
"id":"sources",
"title":"Come viene descritta l’immagine",
"intro":"La prima schermata chiede come viene descritta l’immagine. Quattro opzioni forniscono una definizione da adattare, una quinta usa solo il nome dell’immagine e altre tre leggono un oci-compose già scritto.",
"blocks":[
{
"table":{
"headers":[
"Opzione",
"Cosa legge"
],
"rows":[
[
"Incolla il file Compose nel terminale",
"Incolla il contenuto YAML nel terminale e termina con Ctrl+D."
],
[
"Leggi il file Compose da questo host",
"Un percorso sul nodo, <code>/root/docker-compose.yml</code> per impostazione predefinita. Il file deve esistere e non superare 256 KiB."
],
[
"Scarica il file Compose da un indirizzo",
"Un indirizzo <code>http://</code> o <code>https://</code> che fornisce il contenuto YAML grezzo. Vengono scaricati al massimo 256 KiB."
],
[
"Incolla il comando docker run nel terminale",
"Il comando pubblicato dal progetto. Vengono adattati porte, ambiente, volumi, dispositivi, capability, utente, memoria condivisa e le altre opzioni supportate."
],
[
"Solo il riferimento all’immagine, senza file Compose",
"Un riferimento come <code>ghcr.io/user/application:latest</code>. Viene interrogato il registro e vengono conservati i metadati OCI dell’immagine."
],
[
"Incolla un oci-compose nel terminale",
"Incolla il JSON nel terminale e termina con Ctrl+D. Non viene convertito: viene verificato e installato così come è scritto."
],
[
"Leggi un oci-compose da questo host",
"Un file JSON sul nodo, <code>/root/oci-compose.json</code> per impostazione predefinita, di massimo 2 MiB."
],
[
"Scarica un oci-compose da un indirizzo",
"Un indirizzo <code>http://</code> o <code>https://</code> che fornisce il file JSON. Vengono scaricati al massimo 2 MiB."
]
]
}
},
{
"figure":{
"src":"/oci-manager/custom-source-menu.png",
"alt":"Menu per scegliere come descrivere un’immagine non presente nel catalogo",
"caption":"Modi per descrivere un’immagine non presente nel catalogo."
}
}
]
},
{
"id":"reference-only",
"title":"Cosa fornisce il solo riferimento all’immagine",
"intro":"L’immagine contiene i metadati del processo, ma non tutto l’ambiente che normalmente aggiunge un file Compose.",
"blocks":[
{
"table":{
"headers":[
"Letto dall’immagine",
"Non presente nell’immagine",
"Conseguenza"
],
"rows":[
[
"<code>Entrypoint</code>, <code>Cmd</code>, <code>User</code>, <code>WorkingDir</code> e l’ambiente incorporato",
"Variabili presenti solo nella documentazione",
"Vengono aggiunte durante l’installazione o con Modifica"
],
[
"Volumi dichiarati dall’immagine",
"Directory dell’host indicate solo nel file Compose",
"I percorsi aggiuntivi vengono inseriti prima dell’installazione"
],
[
"Porte <code>EXPOSE</code>",
"L’URL, il protocollo o il controllo funzionale del servizio",
"Vengono confermati la porta e il metodo di verifica del servizio"
],
[
"Architetture e digest nel registro",
"Dispositivi, privilegi o dipendenze esterne",
"Non vengono abilitati senza una definizione che li richieda"
]
]
}
}
]
},
{
"id":"review",
"title":"Verifica prima di installare",
"intro":"Dopo aver adattato la definizione, ProxMenux mostra come l’ha interpretata prima di chiedere VMID, risorse o storage.",
"blocks":[
{
"steps":{
"items":[
{
"title":"Analizza",
"body":"Vengono letti servizi, immagine, porte, percorsi, ambiente, dispositivi, sicurezza e controllo di stato."
},
{
"title":"Interroga il registro",
"body":"L’immagine deve esistere nel registro e vengono elencate le architetture pubblicate. Per un registro privato viene usato l’account salvato per quel registro."
},
{
"title":"Elenca ciò che non viene applicato",
"body":"Vengono elencati label, reti Docker, impostazioni Swarm e altre chiavi che non hanno effetto su un LXC."
},
{
"title":"Blocca le opzioni senza equivalente sicuro",
"body":"Le chiavi senza un equivalente sicuro compaiono in <strong>Opzioni senza equivalente</strong> e impediscono di proseguire con l’installazione. Non vengono ignorate senza avviso."
},
{
"title":"Richiedi i segreti",
"body":"Le variabili il cui nome indica una password, un token o una chiave vengono richieste come dati sensibili durante l’installazione."
}
]
}
},
{
"figure":{
"src":"/oci-manager/custom-review.png",
"alt":"Riepilogo di come ProxMenux ha interpretato il file Compose",
"caption":"Riepilogo mostrato prima che l’installer chieda VMID e risorse."
}
},
{
"p":"Dopo aver accettato il riepilogo, il flusso è quello del catalogo: nome, modalità predefinita o avanzata, VMID, CPU, memoria, rete, avvio con il nodo, percorsi persistenti e aggiuntivi, dispositivi compatibili e riepilogo finale."
"intro":"Un oci-compose è il file JSON da cui viene installata un’applicazione. Il catalogo ne conserva uno per ogni applicazione. Lo stesso formato può essere scritto a mano e installato con questa opzione.",
"blocks":[
{
"p":"In un file scritto a mano l’autore decide immagine, porte, variabili, volumi e domande dell’installazione. ProxMenux completa il resto durante la lettura. Il formato può esprimere ciò che Compose non prevede: il testo di una domanda, una password generata all’installazione, un profilo GPU, il proprietario di ciascun volume, il controllo del primo avvio o le credenziali mostrate alla fine."
},
{
"steps":{
"items":[
{
"title":"Verifica",
"body":"I file con errori non vengono installati. Ogni errore indica il campo interessato; se il JSON non è valido, vengono segnalate riga e colonna."
},
{
"title":"Rivedi",
"body":"Un file valido mostra cosa installa: immagine, indirizzo web, porte, percorsi persistenti, variabili richieste dall’installer e file che verranno scritti."
},
{
"title":"Installa",
"body":"L’installazione è la stessa delle applicazioni del catalogo, con impostazioni predefinite o avanzate."
}
]
}
},
{
"calloutWarning":{
"title":"Un file che determina i privilegi",
"body":"Un oci-compose stabilisce cosa viene montato nel container e con quali privilegi. La revisione lo mostra prima dell’installazione: installa solo file provenienti da fonti attendibili."
}
},
{
"p":"Il <readmeLink>README del motore OCI</readmeLink> descrive il formato blocco per blocco con due esempi completi. Anche il record di un’installazione può essere letto nello stesso modo: viene usato solo il modello originale, senza alcuna delle risposte di quell’installazione."
}
]
},
{
"id":"private-registries",
"title":"Immagini in registri privati",
"intro":"Un’immagine in un registro privato, come un pacchetto privato su GitHub o un repository privato su Docker Hub, viene letta con un account salvato in ProxMenux.",
"blocks":[
{
"steps":{
"items":[
{
"title":"Il registro nega l’accesso all’immagine",
"body":"Quando il registro indica che l’immagine richiede un account, la revisione propone di accedere a quel registro e legge di nuovo l’immagine."
},
{
"title":"Accedi",
"body":"Un nome utente e una password o un token autorizzato a scaricare l’immagine. Il registro li verifica e vengono salvati solo se accettati."
},
{
"title":"Installa e mantieni aggiornato",
"body":"L’account viene usato per scaricare l’immagine durante l’installazione e anche per aggiornamenti, Modifica, Ricrea, watchdog e ricerca degli aggiornamenti del Monitor, su qualsiasi nodo del cluster."
}
]
}
},
{
"p":"<strong>Account dei registri</strong>, nel menu principale di OCI manager Apps, elenca gli account salvati per registro e utente, senza mostrarne i segreti. Da ogni account puoi verificare, scaricare o installare un’immagine e aggiornare o rimuovere le credenziali."
},
{
"list":{
"items":[
"GitHub (<code>ghcr.io</code>): l’utente è l’account GitHub e la password è un token di accesso personale con il permesso <code>read:packages</code>.",
"Docker Hub (<code>docker.io</code>): l’utente è l’account Docker Hub e la password è un token di accesso con permesso di lettura.",
"Altri registri, anche con una porta propria come <code>registry.example.com:5000</code>: nome utente e password o token forniti da quel registro."
]
}
},
{
"calloutInfo":{
"title":"Dove vengono salvati gli account",
"body":"In <code>/etc/pve/priv/proxmenux/registry-auth.json</code>, leggibile solo da root, nella stessa cartella in cui Proxmox conserva le password degli storage. <code>/etc/pve</code> è condiviso tra tutti i nodi del cluster, quindi un account aggiunto su un nodo viene usato su tutti. Il backup dell’host include il file e la disinstallazione di ProxMenux lo rimuove da tutti i nodi."
}
}
]
},
{
"id":"limits",
"title":"Definizioni che non vengono installate",
"blocks":[
{
"list":{
"items":[
"Un Dockerfile senza immagine pubblicata: prima occorre creare l’immagine e pubblicarla in un registro OCI.",
"I file Compose con più servizi usano un LXC nativo per servizio. Ogni applicazione web deve avere un proprio endpoint pubblicato; i volumi con la stessa origine possono condividere una directory dell’host. Le opzioni non supportate, le reti esterne e i servizi senza un controllo di integrità supportato continuano a bloccare l’installazione.",
