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

{
  "meta": {
    "title": "Instalar una imagen fuera del catálogo | ProxMenux",
    "description": "Adapta una imagen OCI a partir de un archivo Compose, una URL, un comando docker run o una referencia de imagen, y revisa qué puede reproducir ProxMenux antes de instalarla."
  },
  "header": {
    "title": "Instalar una imagen que no esté en el catálogo",
    "description": "Tu imagen se adapta a partir de su archivo Compose, de un comando docker run o de su referencia. El resultado se muestra para que lo revises antes de crear ningún LXC.",
    "section": "OCI manager Apps"
  },
  "sections": [
    {
      "id": "intro",
      "blocks": [
        {
          "calloutInfo": {
            "title": "El mismo conversor y el mismo instalador",
            "body": "La opción <strong>Instalar una imagen que no esté en el catálogo</strong> utiliza el mismo conversor y el mismo instalador que las plantillas del catálogo. La diferencia es que el contrato se genera en ese momento a partir de la definición proporcionada y se valida antes de crear ningún LXC."
          }
        }
      ]
    },
    {
      "id": "sources",
      "title": "Cómo se describe la imagen",
      "intro": "La primera pantalla pregunta cómo vas a describir la imagen. Cuatro opciones reciben una definición que se adapta, una quinta usa solo el nombre de la imagen y otras tres leen un oci-compose ya escrito.",
      "blocks": [
        {
          "table": {
            "headers": [
              "Opción",
              "Qué lee"
            ],
            "rows": [
              [
                "Pegar su archivo Compose en la terminal",
                "Pega el YAML en la terminal y termina con Ctrl+D."
              ],
              [
                "Leer su archivo Compose desde este host",
                "Una ruta del nodo; la predeterminada es <code>/root/docker-compose.yml</code>. El archivo debe existir y no superar los 256 KiB."
              ],
              [
                "Descargar su archivo Compose desde una dirección",
                "Una dirección <code>http://</code> o <code>https://</code> que sirva el YAML sin procesar. Se descargan como máximo 256 KiB."
              ],
              [
                "Pegar su comando docker run en la terminal",
                "El comando publicado por el proyecto. Se adaptan los puertos, el entorno, los volúmenes, los dispositivos, las capabilities, el usuario, la memoria compartida y las demás opciones compatibles."
              ],
              [
                "Solo la referencia de imagen, sin archivo Compose",
                "Una referencia como <code>ghcr.io/user/application:latest</code>. Se consulta el registro y se conservan los metadatos OCI de la imagen."
              ],
              [
                "Pegar un oci-compose en la terminal",
                "Pega el JSON en la terminal y termina con Ctrl+D. No se convierte: se valida y se instala tal como está escrito."
              ],
              [
                "Leer un oci-compose desde este host",
                "Un archivo JSON del nodo, <code>/root/oci-compose.json</code> por defecto, de un máximo de 2 MiB."
              ],
              [
                "Descargar un oci-compose desde una dirección",
                "Una dirección <code>http://</code> o <code>https://</code> que sirva el archivo JSON. Se descargan como máximo 2 MiB."
              ]
            ]
          }
        },
        {
          "figure": {
            "src": "/oci-manager/custom-source-menu.png",
            "alt": "Menú para elegir cómo describir una imagen que no está en el catálogo",
            "caption": "Formas de describir una imagen fuera del catálogo."
          }
        }
      ]
    },
    {
      "id": "reference-only",
      "title": "Qué aporta una referencia de imagen por sí sola",
      "intro": "La imagen contiene los metadatos de su proceso, pero no todo el entorno que suele añadir un archivo Compose.",
      "blocks": [
        {
          "table": {
            "headers": [
              "Se lee de la imagen",
              "No está en la imagen",
              "Consecuencia"
            ],
            "rows": [
              [
                "<code>Entrypoint</code>, <code>Cmd</code>, <code>User</code>, <code>WorkingDir</code> y el entorno incorporado",
                "Variables que solo figuran en la documentación",
                "Se añaden durante la instalación o desde Modificar"
              ],
              [
                "Volúmenes declarados por la imagen",
                "Directorios del host que solo se indican en Compose",
                "Las rutas adicionales se añaden antes de instalar"
              ],
              [
                "Puertos <code>EXPOSE</code>",
                "La URL, el protocolo o la comprobación funcional del servicio",
                "Se confirman el puerto y la forma de comprobar el servicio"
              ],
              [
                "Arquitecturas y digest del registro",
                "Dispositivos, privilegios o dependencias externas",
                "No se habilitan sin una definición que los solicite"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "review",
      "title": "Revisar antes de instalar",
      "intro": "Tras adaptar la definición, ProxMenux muestra cómo la ha interpretado antes de preguntar el VMID, los recursos o el almacenamiento.",
      "blocks": [
        {
          "steps": {
            "items": [
              {
                "title": "Analizar",
                "body": "Se leen servicios, imagen, puertos, rutas, entorno, dispositivos, seguridad y comprobaciones de estado."
              },
              {
                "title": "Consultar el registro",
                "body": "La imagen debe existir en el registro y se muestran las arquitecturas publicadas. Si el registro es privado, se utiliza la cuenta guardada para él."
              },
              {
                "title": "Enumerar lo que no se aplica",
                "body": "Se enumeran las etiquetas, redes de Docker, ajustes de Swarm y otras claves que no tienen efecto en un LXC."
              },
              {
                "title": "Bloquear opciones sin equivalente seguro",
                "body": "Las claves sin equivalente seguro aparecen en <strong>Opciones sin equivalente</strong> e impiden continuar con la instalación. No se descartan silenciosamente."
              },
              {
                "title": "Solicitar secretos",
                "body": "Las variables cuyo nombre indica una contraseña, token o clave se solicitan como datos sensibles durante la instalación."
              }
            ]
          }
        },
        {
          "figure": {
            "src": "/oci-manager/custom-review.png",
            "alt": "Resumen de cómo ProxMenux ha interpretado el archivo Compose",
            "caption": "Resumen mostrado antes de que el instalador pregunte el VMID y los recursos."
          }
        },
        {
          "p": "Tras aceptar el resumen se sigue el mismo asistente que en el catálogo: nombre, modo predeterminado o avanzado, VMID, CPU, memoria, red, arranque con el nodo, rutas persistentes, rutas adicionales, dispositivos compatibles y resumen final."
        }
      ]
    },
    {
      "id": "examples",
      "title": "Ejemplos de entrada",
      "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 escrito a mano",
      "intro": "Un oci-compose es el archivo JSON a partir del cual se instala una aplicación. El catálogo conserva uno por aplicación. Puedes escribir el mismo formato a mano e instalarlo con esta opción.",
      "blocks": [
        {
          "p": "Al escribirlo a mano, el autor decide la imagen, los puertos, las variables, los volúmenes y las preguntas de la instalación. ProxMenux completa el resto al leer el archivo. Permite expresar lo que Compose no incluye: el texto de una pregunta, una contraseña generada durante la instalación, un perfil de GPU, el propietario de cada volumen, la comprobación del primer arranque o las credenciales mostradas al final."
        },
        {
          "steps": {
            "items": [
              {
                "title": "Comprobar",
                "body": "Los archivos con errores no se instalan. Cada error indica el campo afectado; si el JSON no es válido, se muestran la línea y la columna."
              },
              {
                "title": "Revisar",
                "body": "Si el archivo es válido, se muestra lo que instalará: imagen, dirección web, puertos, rutas persistentes, variables que solicitará el instalador y archivos que escribirá."
              },
              {
                "title": "Instalar",
                "body": "Se utiliza el mismo instalador que para cualquier aplicación del catálogo, con ajustes predeterminados o avanzados."
              }
            ]
          }
        },
        {
          "calloutWarning": {
            "title": "Un archivo que decide los privilegios",
            "body": "El oci-compose determina qué se monta dentro del contenedor y con qué privilegios. La revisión lo muestra antes de instalar: utiliza únicamente archivos de fuentes de confianza."
          }
        },
        {
          "p": "El <readmeLink>README del motor OCI</readmeLink> explica el formato bloque a bloque e incluye dos ejemplos completos. También se puede leer el registro de una instalación: solo se utiliza la plantilla original, sin incorporar ninguna de las respuestas de aquella instalación."
        }
      ]
    },
    {
      "id": "private-registries",
      "title": "Imágenes de registros privados",
      "intro": "Las imágenes de registros privados, como un paquete privado de GitHub o un repositorio privado de Docker Hub, se consultan con una cuenta guardada en ProxMenux.",
      "blocks": [
        {
          "steps": {
            "items": [
              {
                "title": "El registro deniega el acceso a la imagen",
                "body": "Si el registro indica que la imagen requiere una cuenta, la revisión ofrece iniciar sesión en ese registro y vuelve a consultar la imagen."
              },
              {
                "title": "Iniciar sesión",
                "body": "Un usuario y una contraseña o token con permiso para descargar la imagen. El registro los comprueba y solo se guardan si los acepta."
              },
              {
                "title": "Instalar y mantener al día",
                "body": "Esa cuenta se utiliza para descargar la imagen durante la instalación y también en las actualizaciones, Modificar, Recrear, la vigilancia y la comprobación de actualizaciones del Monitor, en cualquier nodo del clúster."
              }
            ]
          }
        },
        {
          "p": "<strong>Cuentas de registros</strong>, en el menú principal de OCI manager Apps, muestra las cuentas guardadas por registro y usuario, nunca sus secretos. Desde cada cuenta puedes comprobar, descargar o instalar una imagen, actualizar las credenciales o eliminarlas."
        },
        {
          "list": {
            "items": [
              "GitHub (<code>ghcr.io</code>): el usuario es la cuenta de GitHub y la contraseña es un token de acceso personal con permiso <code>read:packages</code>.",
              "Docker Hub (<code>docker.io</code>): el usuario es la cuenta de Docker Hub y la contraseña es un token con permiso de lectura.",
              "Otros registros, incluidos los que usan un puerto propio como <code>registry.example.com:5000</code>: el usuario y la contraseña o token que proporcione ese registro."
            ]
          }
        },
        {
          "calloutInfo": {
            "title": "Dónde se guardan las cuentas",
            "body": "En <code>/etc/pve/priv/proxmenux/registry-auth.json</code>, accesible solo por root, en la misma carpeta donde Proxmox guarda las contraseñas de almacenamiento. <code>/etc/pve</code> se comparte entre los nodos del clúster, de modo que una cuenta añadida en un nodo se utiliza en todos. El backup del host incluye ese archivo y desinstalar ProxMenux lo elimina de todos los nodos."
          }
        }
      ]
    },
    {
      "id": "limits",
      "title": "Definiciones que no se instalan",
      "blocks": [
        {
          "list": {
            "items": [
              "Un Dockerfile sin imagen publicada: primero hay que construir la imagen y publicarla en un registro OCI.",
              "Los archivos Compose con varios servicios usan un LXC nativo por servicio. Cada aplicación web necesita su propio puerto publicado; los volúmenes con el mismo origen pueden compartir un directorio del host. Las opciones no compatibles, las redes externas y los servicios sin una comprobación de salud compatible siguen bloqueando la instalación.",
              "<code>configs</code>, secretos externos o formatos de dispositivo que no puedan adaptarse de forma inequívoca.",
              "Sustituciones de shell como <code>$(command)</code>: hay que escribir directamente el valor resultante.",
              "Opciones de <code>docker run</code> no reconocidas y <code>--env-file</code>: utiliza un archivo Compose con los valores explícitos."
            ]
          }
        }
      ]
    }
  ]
}