mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-11-01 10:22:08 +00:00
MacRimi
248ac5dec6
- Registry accounts are kept in /etc/pve/priv/proxmenux/registry-auth.json, shared by every node, unless REGISTRY_AUTH_FILE says otherwise - The custom image importer offers to sign in when a registry refuses an image, and reads it again - Installers, updates, the watchdog and the Monitor update check read private images with the saved accounts - The host backup includes the accounts, and uninstalling ProxMenux removes them and keeps the OCI records of the cluster - Spanish written by hand and spacing fixed for the registry account messages in every locale - Docs: private registries section, Registry accounts in the OCI menu, README storage notes
206 lines
12 KiB
JSON
206 lines
12 KiB
JSON
{
|
|
"meta": {
|
|
"title": "Instalar una imagen que no está en el catálogo | ProxMenux",
|
|
"description": "Traducción de una imagen OCI desde un archivo Compose, una URL, un comando docker run o una referencia de imagen, con revisión de lo que ProxMenux puede reproducir antes de instalarla."
|
|
},
|
|
"header": {
|
|
"title": "Instalar una imagen que no está en el catálogo",
|
|
"description": "Una imagen propia se traduce desde su archivo Compose, un comando docker run o solo su referencia, y el resultado se presenta para revisión antes de crear ningún LXC.",
|
|
"section": "OCI manager Apps"
|
|
},
|
|
"sections": [
|
|
{
|
|
"id": "intro",
|
|
"blocks": [
|
|
{
|
|
"calloutInfo": {
|
|
"title": "El mismo conversor, el mismo instalador",
|
|
"body": "La opción <strong>Instalar una imagen que no está en el catálogo</strong> utiliza el conversor y el instalador de las plantillas del catálogo. La diferencia es que el contrato se genera en ese momento a partir de la definición aportada 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 se describe la imagen. Cuatro formas aportan una definición que se traduce, una quinta usa solo el nombre de la imagen y tres reciben un oci-compose ya escrito.",
|
|
"blocks": [
|
|
{
|
|
"table": {
|
|
"headers": ["Opción", "Qué lee"],
|
|
"rows": [
|
|
["Pegar su archivo Compose en la terminal", "El YAML se pega en la terminal y termina con Ctrl+D."],
|
|
["Leer su archivo Compose desde un archivo de este host", "Una ruta del nodo, <code>/root/docker-compose.yml</code> por defecto. El archivo debe existir y ocupar como máximo 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 que publica el proyecto. Se traducen puertos, entorno, volúmenes, dispositivos, capacidades, usuario, memoria compartida y el resto de opciones admitidas."],
|
|
["Solo la referencia de la 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", "El JSON se pega en la terminal y termina con Ctrl+D. No se traduce: se comprueba y se instala tal como está escrito."],
|
|
["Leer un oci-compose desde un archivo de este host", "Un archivo JSON del nodo, <code>/root/oci-compose.json</code> por defecto, de 2 MiB como máximo."],
|
|
["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ú que pregunta cómo se describe una imagen que no está en el catálogo",
|
|
"caption": "Las formas de describir una imagen que no está en el catálogo."
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "reference-only",
|
|
"title": "Qué aporta solo la referencia de la imagen",
|
|
"intro": "Una imagen lleva sus metadatos de proceso, pero no todo lo que un archivo Compose suele añadir a su alrededor.",
|
|
"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 entorno integrado", "Variables que solo aparecen en la documentación", "Se añaden durante la instalación o con Modificar"],
|
|
["Volúmenes declarados por la imagen", "Directorios del host que solo nombra un archivo Compose", "Las rutas adicionales se añaden antes de instalar"],
|
|
["Puertos <code>EXPOSE</code>", "La URL, el protocolo o un healthcheck funcional", "Se confirman el puerto y la forma de comprobar el servicio"],
|
|
["Arquitecturas y digest del registro", "Dispositivos, privilegios o dependencias externas", "Ninguno se activa sin una definición que lo pida"]
|
|
]
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "review",
|
|
"title": "Revisión antes de instalar",
|
|
"intro": "Tras traducir la definición, ProxMenux muestra lo que ha entendido antes de pedir VMID, recursos o almacenamiento.",
|
|
"blocks": [
|
|
{
|
|
"steps": {
|
|
"items": [
|
|
{ "title": "Analizar", "body": "Se leen servicios, imagen, puertos, rutas, entorno, dispositivos, seguridad y healthcheck." },
|
|
{ "title": "Consultar el registro", "body": "La imagen debe existir en su registro, y se enumeran las arquitecturas que publica. Un registro privado se lee con la cuenta guardada para él." },
|
|
{ "title": "Enumerar lo que no se aplica", "body": "Se enumeran las etiquetas, las redes Docker, los ajustes de Swarm y el resto de claves que no tienen efecto en un LXC." },
|
|
{ "title": "Bloquear lo que no puede traducirse", "body": "Una clave sin equivalencia segura aparece en <strong>Lo que no puede traducirse</strong> y la instalación no continúa. Nada se descarta en silencio." },
|
|
{ "title": "Pedir los secretos", "body": "Las variables cuyo nombre corresponde a una contraseña, un token o una clave se convierten en preguntas sensibles de la instalación." }
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"figure": {
|
|
"src": "/oci-manager/custom-review.png",
|
|
"alt": "Resumen de lo que ProxMenux ha entendido de un archivo Compose",
|
|
"caption": "El resumen que se muestra antes de que la instalación pida VMID y recursos."
|
|
}
|
|
},
|
|
{
|
|
"p": "Tras aceptar el resumen, el recorrido es el del 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 desde el que se instala una aplicación. El catálogo guarda uno por cada aplicación, y el mismo formato puede escribirse a mano e instalarse con esta opción.",
|
|
"blocks": [
|
|
{
|
|
"p": "El que se escribe a mano indica lo que decide su autor: la imagen, sus puertos, variables y volúmenes, y lo que pregunta la instalación. ProxMenux completa el resto al leer el archivo. Puede decir lo que un archivo Compose no puede: 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 que se muestran al terminar."
|
|
},
|
|
{
|
|
"steps": {
|
|
"items": [
|
|
{
|
|
"title": "Comprobar",
|
|
"body": "Un archivo con errores no se instala. Cada error indica el campo en el que está, y un archivo que no es JSON válido indica la línea y la columna."
|
|
},
|
|
{
|
|
"title": "Revisar",
|
|
"body": "Un archivo válido muestra lo que instala: imagen, dirección web, puertos, rutas persistentes, las variables que pide la instalación y los archivos que escribe."
|
|
},
|
|
{
|
|
"title": "Instalar",
|
|
"body": "La instalación es la de cualquier aplicación del catálogo, con ajustes por defecto o avanzados."
|
|
}
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"calloutWarning": {
|
|
"title": "Un archivo que decide privilegios",
|
|
"body": "Un oci-compose decide qué se monta en el contenedor y con qué privilegios. El resumen lo indica antes de instalar: instala solo archivos que vengan de una fuente de confianza."
|
|
}
|
|
},
|
|
{
|
|
"p": "El formato se describe bloque a bloque, con dos ejemplos completos, en el <readmeLink>README del motor OCI</readmeLink>. El registro de una instalación se lee de la misma forma: solo se usa la plantilla con la que se instaló, y ninguna de las respuestas de esa instalación."
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "private-registries",
|
|
"title": "Imágenes en registros privados",
|
|
"intro": "Una imagen en un registro privado, como un paquete privado de GitHub o un repositorio privado de Docker Hub, se lee con una cuenta guardada en ProxMenux.",
|
|
"blocks": [
|
|
{
|
|
"steps": {
|
|
"items": [
|
|
{ "title": "El registro rechaza la imagen", "body": "Cuando el registro responde que la imagen necesita una cuenta, la revisión ofrece iniciar sesión en ese registro y vuelve a leer la imagen." },
|
|
{ "title": "Iniciar sesión", "body": "Un usuario y una contraseña o un token de acceso que puedan descargar la imagen. El registro los comprueba y solo se guardan si los acepta." },
|
|
{ "title": "Instalar y mantener al día", "body": "La instalación descarga la imagen con esa cuenta, y también las actualizaciones, Modificar, Recrear, la vigilancia y la comprobación de actualizaciones del Monitor, en cualquier nodo del clúster." }
|
|
]
|
|
}
|
|
},
|
|
{ "p": "<strong>Cuentas de registro</strong>, en el menú principal de OCI manager Apps, lista las cuentas guardadas por registro y usuario, nunca su secreto. Desde cada cuenta se puede comprobar, descargar o instalar una imagen, y actualizar o eliminar la cuenta." },
|
|
{
|
|
"list": {
|
|
"items": [
|
|
"GitHub (<code>ghcr.io</code>): el usuario es la cuenta de GitHub, y la contraseña un token de acceso personal con el permiso <code>read:packages</code>.",
|
|
"Docker Hub (<code>docker.io</code>): el usuario es la cuenta de Docker Hub, y la contraseña un token de acceso con permiso de lectura.",
|
|
"Otros registros, también uno con su propio puerto como <code>registry.example.com:5000</code>: el usuario y la contraseña o token que da ese registro."
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"calloutInfo": {
|
|
"title": "Dónde se guardan",
|
|
"body": "En <code>/etc/pve/priv/proxmenux/registry-auth.json</code>, legible solo por root, en la misma carpeta donde Proxmox guarda las contraseñas de sus almacenamientos. <code>/etc/pve</code> lo comparten todos los nodos del clúster, así que una cuenta añadida en un nodo se usa en todos. El backup del host lo incluye, y al desinstalar ProxMenux se elimina de todos los nodos."
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "limits",
|
|
"title": "Definiciones que no se instalan",
|
|
"blocks": [
|
|
{
|
|
"list": {
|
|
"items": [
|
|
"Un Dockerfile sin imagen publicada: la imagen debe construirse y publicarse antes en un registro OCI.",
|
|
"Un archivo Compose con varios servicios: queda bloqueado porque describe más de una imagen. Esta opción instala un único contenedor.",
|
|
"<code>configs</code>, secretos externos o formatos de dispositivo que no pueden traducirse sin ambigüedad.",
|
|
"Sustituciones del shell como <code>$(command)</code>: debe escribirse el valor resultante.",
|
|
"Opciones de <code>docker run</code> no reconocidas y <code>--env-file</code>: se lee en su lugar un archivo Compose explícito."
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|