{
  "meta": {
    "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."
        }
      ]
    },
    {
      "id": "examples",
      "title": "Esempi di input",
      "blocks": [
        {
          "codeGrid": {
            "items": [
              {
                "title": "Compose",
                "code": "services:\n  app:\n    image: ghcr.io/example/app:latest\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - ./config:/config\n      - /srv/media:/media\n    environment:\n      TZ: Europe/Madrid"
              },
              {
                "title": "docker run",
                "code": "docker run -d \\\n  --name app \\\n  -p 8080:8080 \\\n  -e TZ=Europe/Madrid \\\n  -v app-config:/config \\\n  -v /srv/media:/media \\\n  ghcr.io/example/app:latest"
              }
            ]
          }
        }
      ]
    },
    {
      "id": "oci-compose",
      "title": "Un oci-compose scritto a mano",
      "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.",
              "<code>configs</code>, segreti esterni o formati di dispositivi che non possono essere adattati senza ambiguità.",
              "Sostituzioni della shell come <code>$(command)</code>: occorre inserire direttamente il valore risultante.",
              "Opzioni <code>docker run</code> non riconosciute e <code>--env-file</code>: usa invece un file Compose con valori espliciti."
            ]
          }
        }
      ]
    }
  ]
}