ProxMenux/web/messages/en/docs/oci-manager/custom-image.json

{
  "meta": {
    "title": "Install an image that is not in the catalog | ProxMenux",
    "description": "Translate an OCI image from a Compose file, a URL, a docker run command or an image reference, and review what ProxMenux can reproduce before installing it."
  },
  "header": {
    "title": "Install an image that is not in the catalog",
    "description": "An image of your own is translated from its Compose file, a docker run command or its reference alone, and the result is shown for review before any LXC is created.",
    "section": "OCI manager Apps"
  },
  "sections": [
    {
      "id": "intro",
      "blocks": [
        {
          "calloutInfo": {
            "title": "Same converter, same installer",
            "body": "The option <strong>Install an image that is not in the catalog</strong> uses the converter and the installer of the catalog templates. The difference is that the contract is generated at that moment from the definition given, and validated before any LXC is created."
          }
        }
      ]
    },
    {
      "id": "sources",
      "title": "How the image is described",
      "intro": "The first screen asks how the image is described. Four ways give a definition that is translated, a fifth uses only the image name, and three take an oci-compose that is already written.",
      "blocks": [
        {
          "table": {
            "headers": ["Option", "What it reads"],
            "rows": [
              ["Paste its Compose file in the terminal", "The YAML is pasted in the terminal and ends with Ctrl+D."],
              ["Read its Compose file from a file of this host", "A path on the node, <code>/root/docker-compose.yml</code> by default. The file must exist and be at most 256 KiB."],
              ["Download its Compose file from an address", "An <code>http://</code> or <code>https://</code> address that serves the raw YAML. At most 256 KiB are downloaded."],
              ["Paste its docker run command in the terminal", "The command published by the project. Ports, environment, volumes, devices, capabilities, user, shared memory and the other supported options are translated."],
              ["Only the image reference, with no Compose file", "A reference such as <code>ghcr.io/user/application:latest</code>. The registry is queried and the OCI metadata of the image is kept."],
              ["Paste an oci-compose in the terminal", "The JSON is pasted in the terminal and ends with Ctrl+D. It is not translated: it is checked and installed as it is written."],
              ["Read an oci-compose from a file of this host", "A JSON file on the node, <code>/root/oci-compose.json</code> by default, of at most 2 MiB."],
              ["Download an oci-compose from an address", "An <code>http://</code> or <code>https://</code> address that serves the JSON file. At most 2 MiB are downloaded."]
            ]
          }
        },
        {
          "figure": {
            "src": "/oci-manager/custom-source-menu.png",
            "alt": "Menu that asks how an image that is not in the catalog is described",
            "caption": "The ways to describe an image that is not in the catalog."
          }
        }
      ]
    },
    {
      "id": "reference-only",
      "title": "What an image reference alone provides",
      "intro": "An image carries its process metadata, but not everything a Compose file usually adds around it.",
      "blocks": [
        {
          "table": {
            "headers": ["Read from the image", "Not in the image", "Consequence"],
            "rows": [
              ["<code>Entrypoint</code>, <code>Cmd</code>, <code>User</code>, <code>WorkingDir</code> and embedded environment", "Variables that only appear in the documentation", "They are added during the installation or with Modify"],
              ["Volumes declared by the image", "Host directories that only a Compose file names", "Additional paths are added before installing"],
              ["<code>EXPOSE</code> ports", "The URL, protocol or functional healthcheck", "The port and the way the service is checked are confirmed"],
              ["Architectures and digest in the registry", "Devices, privileges or external dependencies", "None of them is enabled without a definition that asks for it"]
            ]
          }
        }
      ]
    },
    {
      "id": "review",
      "title": "Review before installing",
      "intro": "After translating the definition, ProxMenux shows what it understood before asking for VMID, resources or storage.",
      "blocks": [
        {
          "steps": {
            "items": [
              { "title": "Analyse", "body": "Services, image, ports, paths, environment, devices, security and healthcheck are read." },
              { "title": "Query the registry", "body": "The image must exist in its registry, and its published architectures are listed. A private registry is read with the account saved for it." },
              { "title": "List what is not applied", "body": "Labels, Docker networks, Swarm settings and other keys that have no effect on an LXC are listed." },
              { "title": "Block what cannot be translated", "body": "A key with no safe equivalent is shown under <strong>What cannot be translated</strong> and the installation does not continue. Nothing is dropped silently." },
              { "title": "Ask for secrets", "body": "Variables whose names read as a password, token or key become sensitive questions of the installation." }
            ]
          }
        },
        {
          "figure": {
            "src": "/oci-manager/custom-review.png",
            "alt": "Summary of what ProxMenux understood from a Compose file",
            "caption": "The summary shown before the installation asks for VMID and resources."
          }
        },
        {
          "p": "After accepting the summary, the flow is the one of the catalog: name, default or advanced mode, VMID, CPU, memory, network, start with the node, persistent paths, additional paths, compatible devices and a final summary."
        }
      ]
    },
    {
      "id": "examples",
      "title": "Input examples",
      "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": "An oci-compose written by hand",
      "intro": "An oci-compose is the JSON file an application is installed from. The catalog keeps one for each of its applications, and the same format can be written by hand and installed with this option.",
      "blocks": [
        {
          "p": "One written by hand states what its author decides: the image, its ports, variables and volumes, and what the installation asks. ProxMenux completes the rest when it reads the file. It can say what a Compose file cannot: the text of a question, a password generated during the installation, a GPU profile, the owner of each volume, the check of the first start or the credentials shown at the end."
        },
        {
          "steps": {
            "items": [
              {
                "title": "Check",
                "body": "A file with errors is not installed. Each error names the field it is in, and a file that is not valid JSON reports the line and the column."
              },
              {
                "title": "Review",
                "body": "A valid file shows what it installs: image, web address, ports, persistent paths, the variables the installation asks for and the files it writes."
              },
              {
                "title": "Install",
                "body": "The installation is the one of any application of the catalog, with default or advanced settings."
              }
            ]
          }
        },
        {
          "calloutWarning": {
            "title": "A file that decides privileges",
            "body": "An oci-compose decides what is mounted in the container and with which privileges. The review says it before installing: install only files that come from a source you trust."
          }
        },
        {
          "p": "The format is described block by block, with two complete examples, in the <readmeLink>README of the OCI engine</readmeLink>. The record of an installation can be read the same way: only the template it was installed from is used, and none of the answers of that installation."
        }
      ]
    },
    {
      "id": "private-registries",
      "title": "Images in private registries",
      "intro": "An image in a private registry, such as a private package on GitHub or a private repository on Docker Hub, is read with an account saved in ProxMenux.",
      "blocks": [
        {
          "steps": {
            "items": [
              { "title": "The registry refuses the image", "body": "When the registry answers that the image needs an account, the review offers to sign in to that registry and reads the image again." },
              { "title": "Sign in", "body": "A user and a password or access token that can pull the image. The registry checks them, and they are saved only if it accepts them." },
              { "title": "Install and keep up to date", "body": "The installation downloads the image with that account, and so do updates, Modify, Recreate, the watchdog and the update check of the Monitor, on any node of the cluster." }
            ]
          }
        },
        { "p": "<strong>Registry accounts</strong>, in the main menu of OCI manager Apps, lists the saved accounts by registry and user, never their secret. From each account an image can be checked, downloaded or installed, and the account updated or removed." },
        {
          "list": {
            "items": [
              "GitHub (<code>ghcr.io</code>): the user is the GitHub account, and the password a personal access token with the <code>read:packages</code> permission.",
              "Docker Hub (<code>docker.io</code>): the user is the Docker Hub account, and the password an access token with read permission.",
              "Other registries, including one with its own port such as <code>registry.example.com:5000</code>: the user and password or token that registry gives."
            ]
          }
        },
        {
          "calloutInfo": {
            "title": "Where the accounts are kept",
            "body": "In <code>/etc/pve/priv/proxmenux/registry-auth.json</code>, readable only by root, in the same folder where Proxmox keeps its storage passwords. <code>/etc/pve</code> is shared by every node of the cluster, so an account added on one node is used on all of them. The host backup includes it, and uninstalling ProxMenux removes it from every node."
          }
        }
      ]
    },
    {
      "id": "limits",
      "title": "Definitions that are not installed",
      "blocks": [
        {
          "list": {
            "items": [
              "A Dockerfile without a published image: the image has to be built and published in an OCI registry first.",
              "A Compose file with several services is blocked: this option installs one service in one container at a time, even when several services use the same image.",
              "<code>configs</code>, external secrets or device formats that cannot be translated unambiguously.",
              "Shell substitutions such as <code>$(command)</code>: the resulting value has to be written instead.",
              "<code>docker run</code> options that are not recognised, and <code>--env-file</code>: an explicit Compose file is read instead."
            ]
          }
        }
      ]
    }
  ]
}