mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-11-02 02:42:08 +00:00
Merge pull request #558 from jcastro/docs/oci-catalog-contributor-guide
docs(oci): add reusable app catalog guide
This commit is contained in:
MacRimi
@@ -0,0 +1,31 @@
|
||||
import type { Metadata } from "next"
|
||||
import { getTranslations, setRequestLocale } from "next-intl/server"
|
||||
import { DocPage } from "@/components/docs/DocBlocks"
|
||||
|
||||
const NAMESPACE = "docs.ociManager.contributeApp"
|
||||
const URL = "https://proxmenux.com/docs/oci-manager/contribute-app"
|
||||
|
||||
const LINKS = {
|
||||
proposals: "https://github.com/MacRimi/ProxMenux/discussions/440",
|
||||
readme: "https://github.com/MacRimi/ProxMenux/blob/develop/oci/README.md#writing-and-testing-an-oci-compose",
|
||||
roadmap: "https://github.com/users/MacRimi/projects/1",
|
||||
catalog: "https://github.com/MacRimi/ProxMenux/tree/develop/oci/catalog",
|
||||
validation: "https://github.com/MacRimi/ProxMenux/blob/develop/oci/VALIDATION.md",
|
||||
}
|
||||
|
||||
export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }): Promise<Metadata> {
|
||||
const { locale } = await params
|
||||
const t = await getTranslations({ locale, namespace: `${NAMESPACE}.meta` })
|
||||
return {
|
||||
title: t("title"),
|
||||
description: t("description"),
|
||||
alternates: { canonical: URL },
|
||||
openGraph: { title: t("title"), description: t("description"), type: "article", url: URL },
|
||||
}
|
||||
}
|
||||
|
||||
export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
|
||||
const { locale } = await params
|
||||
setRequestLocale(locale)
|
||||
return <DocPage locale={locale} namespace={NAMESPACE} minutes={12} links={LINKS} />
|
||||
}
|
||||
@@ -111,6 +111,7 @@ export const sidebarItems: MenuItem[] = [
|
||||
{ title: "Data, paths and networking", i18nKey: "ociStorageNetwork", href: "/docs/oci-manager/storage-network" },
|
||||
{ title: "Devices and acceleration", i18nKey: "ociHardware", href: "/docs/oci-manager/hardware" },
|
||||
{ title: "Multi-container applications", i18nKey: "ociStacks", href: "/docs/oci-manager/stacks" },
|
||||
{ title: "Install an app and contribute it", i18nKey: "ociContributeApp", href: "/docs/oci-manager/contribute-app" },
|
||||
{ title: "Install, update and recreate", i18nKey: "ociLifecycle", href: "/docs/oci-manager/lifecycle" },
|
||||
{ title: "In ProxMenux Monitor", i18nKey: "ociMonitor", href: "/docs/oci-manager/monitor" },
|
||||
],
|
||||
|
||||
@@ -216,6 +216,14 @@ export async function DocPage({
|
||||
</div>
|
||||
)
|
||||
|
||||
case "agentPrompt":
|
||||
return (
|
||||
<div key={index} className="mb-6 overflow-hidden rounded-lg border border-blue-200 bg-white">
|
||||
{data.title && <div className="border-b border-blue-200 bg-blue-50 px-4 py-2 text-sm font-semibold text-gray-900">{t(`${base}.title`)}</div>}
|
||||
<pre className="whitespace-pre-wrap break-words bg-white p-4 text-sm leading-6 text-gray-800">{t(`${base}.body`)}</pre>
|
||||
</div>
|
||||
)
|
||||
|
||||
case "codeGrid":
|
||||
return (
|
||||
<div key={index} className="mb-6 grid gap-4 lg:grid-cols-2">
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Daten, Pfade und Netzwerk",
|
||||
"ociHardware": "Geräte und Beschleunigung",
|
||||
"ociStacks": "Anwendungen mit mehreren Containern",
|
||||
"ociContributeApp": "Eine App installieren und zum Katalog beitragen",
|
||||
"ociLifecycle": "Installieren, aktualisieren und ändern",
|
||||
"ociMonitor": "In ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Anwendung, Datenbank und Cache als koordinierte LXCs."
|
||||
},
|
||||
{
|
||||
"label": "Eine App installieren und zum Katalog beitragen",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "Anleitung für Agenten, Tests und Katalog-Pull-Request."
|
||||
},
|
||||
{
|
||||
"label": "Installieren, aktualisieren und ändern",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Data, paths and networking",
|
||||
"ociHardware": "Devices and acceleration",
|
||||
"ociStacks": "Multi-container applications",
|
||||
"ociContributeApp": "Install an app and contribute it",
|
||||
"ociLifecycle": "Install, update and modify",
|
||||
"ociMonitor": "In ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Install an app and add it to the OCI catalog | ProxMenux",
|
||||
"description": "A reusable brief for an agent: install a self-hosted app with OCI manager Apps, verify it, and prepare a catalog contribution for everyone."
|
||||
},
|
||||
"header": {
|
||||
"title": "Install an app and add it to the OCI catalog",
|
||||
"description": "A practical brief you can give to your agent to deploy the app you want, check it on your own Proxmox system, and prepare a reusable ProxMenux OCI catalog entry for others.",
|
||||
"section": "OCI manager Apps"
|
||||
},
|
||||
"sections": [
|
||||
{
|
||||
"id": "purpose",
|
||||
"title": "One request, two outcomes",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Use this guide when you want an agent to install a self-hosted application on the Proxmox system you choose and propose it for the ProxMenux OCI catalog. The guide is intended for different users, Proxmox hosts, CPU architectures, storage backends and hardware. It does not assume a particular computer or homelab."
|
||||
},
|
||||
{
|
||||
"cards": {
|
||||
"items": [
|
||||
{
|
||||
"icon": "server",
|
||||
"title": "Your app",
|
||||
"body": "The requested service is installed and checked on the Proxmox system you selected. Keep this instance and its data unless you ask to remove it."
|
||||
},
|
||||
{
|
||||
"icon": "boxes",
|
||||
"title": "The catalog entry",
|
||||
"body": "The agent checks the upstream image, writes an oci-compose for it, tests it as far as the available system allows and prepares a pull request for other ProxMenux users."
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutWarning": {
|
||||
"title": "A test on one system does not prove support everywhere",
|
||||
"body": "The agent must identify the actual Proxmox version, CPU architecture, storage, network and available devices. Report which combinations were tested. Never claim support for another architecture, GPU, NPU, USB device or storage type by inference."
|
||||
}
|
||||
},
|
||||
{
|
||||
"p": "A catalog entry is not automatically shown as verified, with a ✓ in the installer lists. That mark follows the project's separate <validation>validation process</validation>. A successful download or container start is not enough to claim the app works."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "brief",
|
||||
"title": "Copy this brief to your agent",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Replace the bracketed details if you know them. Your agent should inspect the selected Proxmox system and the current repository for the rest, then report any decision that needs your input."
|
||||
},
|
||||
{
|
||||
"agentPrompt": {
|
||||
"title": "Reusable request",
|
||||
"body": "I want to install [APP NAME] on the Proxmox system I select, using OCI manager Apps. If it is suitable, I also want you to prepare a contribution to the ProxMenux OCI catalog so other users can install it.\n\nUpstream project or image (if known): [LINK OR UNKNOWN]\nProxmox system to use: [SELECTED HOST OR UNKNOWN]\nSpecial requirements (if known): [DATA, NETWORK, GPU/USB, HTTPS, OR NONE]\n\nPlease work through these steps:\n1. Inspect the selected Proxmox host and report its Proxmox VE version, architecture, available storage, network options and relevant devices. Do not assume a specific architecture or hardware.\n2. Check the upstream project and image, the current ProxMenux catalog, open pull requests and recent maintainer guidance. Do not add a duplicate. Applications are suggested for the catalog in discussion #440 (https://github.com/MacRimi/ProxMenux/discussions/440): if it is not there yet, suggest it with its image, the registry it is published in and its category. The catalog uses the developer-published image when one exists; identify its publisher accurately.\n3. Install my requested app through OCI manager Apps. Review the image, resources, data paths, network and variables before confirming. Protect existing services and data. Keep this requested app installed after testing unless I ask you to remove it.\n4. Check that the service actually responds and that its login or first-run setup works. Record what you observed; do not claim untested features.\n5. Write the oci-compose for the catalog entry, following oci/README.md and the files in oci/examples/, and prepare the icon. If the app needs several services, represent and test the full stack using the current ProxMenux approach; do not omit required databases, caches or internal networking.\n6. Run the repository checks, including `cd oci && python3 -m unittest discover -s tests -p 'test_*.py'` as an unprivileged user on a copy of the repository, never on a production host, plus relevant catalog, documentation and offline translation checks. Fix failures caused by this change and rerun the checks.\n7. Validate the catalog candidate with disposable test instances where practical. Do not use my retained app or its data for destructive update, restore or removal tests. Record unavailable hardware and untested cases honestly.\n8. Prepare a focused pull request with the app name, image, icon, concise test results and limitations, and attach the tested oci-compose to the suggestion in discussion #440. Check all required CI results and maintainer comments. Do not merge the pull request.\n9. Clean up only temporary test guests, temporary files and test backups created for this work. Preserve my requested installation, its data, and all unrelated guests and backups.\n\nBefore making an irreversible change, exposing the service publicly, or deleting anything that may contain my data, stop and ask me. Do not put passwords, tokens or private configuration in the repository or pull request. Finish with the app URL or connection details, the pull request link, checks observed, cleanup performed and any remaining limitations."
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutTip": {
|
||||
"title": "Keep credentials private",
|
||||
"body": "Enter registry credentials and app secrets only in the intended local interface. The catalog, screenshots, logs and pull request must contain redacted values, never real passwords or tokens."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "research",
|
||||
"title": "What the agent should establish first",
|
||||
"blocks": [
|
||||
{
|
||||
"steps": {
|
||||
"items": [
|
||||
{
|
||||
"title": "Check the requested host",
|
||||
"body": "Record the Proxmox VE version and host architecture. Identify available storage, bridges, address assignment and relevant GPU, NPU or USB devices. Check the registry manifest for the app image on that architecture. A manifest for amd64 does not prove arm64 support, or vice versa."
|
||||
},
|
||||
{
|
||||
"title": "Check the app and catalog",
|
||||
"body": "Read the developer's documentation and deployment example. Check the <proposals>suggestions for the OCI catalog</proposals>, the <roadmap>roadmap</roadmap>, the <catalog>catalog</catalog> and open pull requests for duplicates or current design decisions, and suggest the app there first. The catalog uses the developer-published image when one exists; a community image needs its publisher verified and named."
|
||||
},
|
||||
{
|
||||
"title": "Understand the full deployment",
|
||||
"body": "Record images, commands, ports, environment variables, volumes, user and permissions, health checks, first-run behavior, credentials, dependencies and optional hardware. For a multi-service app, include the database, cache and internal network when required. Identify Compose behavior that has no safe Proxmox equivalent instead of dropping it silently."
|
||||
},
|
||||
{
|
||||
"title": "Resolve the image",
|
||||
"body": "Use the Skopeo flow of OCI manager Apps to resolve and download the image and verify its layers. If it fails, identify the actual cause: credentials, missing image or tag, unsupported architecture, network trouble or registry rate limit."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "install",
|
||||
"title": "Install and check the app you asked for",
|
||||
"blocks": [
|
||||
{
|
||||
"list": {
|
||||
"items": [
|
||||
"Use OCI manager Apps for the deployment. Choose an unused test VMID where needed, and use the storage, bridge, address and resource settings appropriate to the selected host and the user's request.",
|
||||
"Before confirmation, review the image, resources, persistent paths, network and variables. Keep secrets hidden. For advanced installation, compare the selected VMID, CPU, RAM, storage, bridge, variables and supported device mappings with the resulting `pct config`.",
|
||||
"Use the credential method the app actually provides: user-entered, generated by the installer, printed on first start or documented by the image. Confirm the credentials work, and redact them from evidence.",
|
||||
"Check the real service. For a web app, open the shown URL and confirm the page or login loads. For a non-web service, verify its expected protocol and port. Use HTTPS or a reverse proxy only when needed for the requested test or deployment.",
|
||||
"Where the installer offers them, test both Proxmox-managed volumes and host directories. Create app data and verify that it persists in the expected location with the required permissions.",
|
||||
"Restart the app or stack and confirm it returns with its data and working credentials. Test only the hardware actually available; otherwise record the missing device and leave that integration unverified."
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutDanger": {
|
||||
"title": "Protect the installation the user wants to keep",
|
||||
"body": "Backup restore, unhealthy-image rollback and removal can be destructive. Run those checks only against disposable test instances or after an explicit plan protects the requested installation and its data. Never remove the user's requested app as routine cleanup."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "catalog",
|
||||
"title": "Prepare and validate the catalog entry",
|
||||
"blocks": [
|
||||
{
|
||||
"list": {
|
||||
"items": [
|
||||
"Follow the oci-compose guide in <readme>oci/README.md</readme> and the files in `oci/examples/`. Add a unique ID, accurate category, upstream attribution, documentation links, supported architectures, correct image reference and the app's icon. Check that the icon is the right product and renders correctly.",
|
||||
"Preserve the image's startup behavior, ports, environment and persistent paths. Mark secrets as sensitive. Set data ownership and permissions from upstream evidence, not guesswork.",
|
||||
"Use conservative defaults and expose optional settings deliberately. Advertise GPU, NPU, USB or architecture support only when the current ProxMenux flow supports it and the requirement is documented.",
|
||||
"Represent every required service in a multi-service app and preserve dependencies, private networking, health checks, persistent paths and coordinated operations. Keep a complex stack or shared engine change separate when maintainers can review it more safely that way.",
|
||||
"Run the full OCI engine suite as an unprivileged user on a copy of the repository, even if CI does not run it. Run relevant schema, catalog, documentation, i18n and validation-record checks. Never edit the generated `oci/VALIDATION.md` page by hand: `python3 .github/scripts/oci_validation.py render` regenerates it."
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"shell": {
|
||||
"code": "cd oci && python3 -m unittest discover -s tests -p 'test_*.py'"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "lifecycle",
|
||||
"title": "Lifecycle checks for a disposable catalog test",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Use a separate test instance for checks that update, restore or remove an app. Exercise the options the app actually supports and the test host can provide. For each row, report PASS, FAIL, BLOCKED, NOT APPLICABLE or NOT TESTED and include observable evidence."
|
||||
},
|
||||
{
|
||||
"table": {
|
||||
"headers": [
|
||||
"Check",
|
||||
"What counts as a pass"
|
||||
],
|
||||
"rows": [
|
||||
[
|
||||
"Image download",
|
||||
"Skopeo resolves the intended reference and verifies its layers. Any failure identifies the cause."
|
||||
],
|
||||
[
|
||||
"Default install",
|
||||
"The confirmation summary is accurate; the LXC or full stack starts, gets network connectivity and passes first-start checks."
|
||||
],
|
||||
[
|
||||
"Advanced settings",
|
||||
"Representative VMID, CPU, RAM, storage, bridge, variables and supported devices match the saved Proxmox configuration."
|
||||
],
|
||||
[
|
||||
"Credentials and response",
|
||||
"The displayed or configured credentials work. The web page/login loads, or the expected non-web service responds."
|
||||
],
|
||||
[
|
||||
"Persistent data",
|
||||
"Managed storage and host-directory options behave as documented; created data survives restart with correct permissions."
|
||||
],
|
||||
[
|
||||
"Restart",
|
||||
"The app or stack starts automatically and retains its data and configuration."
|
||||
],
|
||||
[
|
||||
"Backup and restore",
|
||||
"A Proxmox backup restored to another disposable VMID starts, responds and appears in Manage installed OCI applications."
|
||||
],
|
||||
[
|
||||
"Update and rollback",
|
||||
"An image update keeps data, credentials, network, devices and Proxmox settings. Test rollback if safe; otherwise mark it NOT TESTED."
|
||||
],
|
||||
[
|
||||
"Modify",
|
||||
"A supported setting changes, prior settings remain, and the app still responds. Non-image changes should not pull or recreate the app unnecessarily."
|
||||
],
|
||||
[
|
||||
"Removal",
|
||||
"Manage installed OCI applications removes the test LXC(s), disks and records. Host data directories remain. Remove only backups made for disposable test VMIDs."
|
||||
]
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutInfo": {
|
||||
"title": "Report hardware limits clearly",
|
||||
"body": "If the app interface starts but an optional camera, coordinator, GPU, NPU or USB device is absent, the interface check may pass while that hardware integration remains NOT TESTED. State which device and host capability are needed."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "pr",
|
||||
"title": "Prepare the pull request and hand off the result",
|
||||
"blocks": [
|
||||
{
|
||||
"steps": {
|
||||
"items": [
|
||||
{
|
||||
"title": "Show what was really tested",
|
||||
"body": "Include app name, catalog ID, image and digest, Proxmox VE version, architecture, install mode, storage, network, device profile, and the actual response check. Summarize lifecycle outcomes and list blocked, unavailable and untested cases. Include the icon and OCI engine test result."
|
||||
},
|
||||
{
|
||||
"title": "Check project feedback",
|
||||
"body": "After opening the pull request, inspect every required CI check on its current head. Read maintainer comments and reviews, make requested changes and rerun affected checks. Do not report the PR as ready while a required check is failing or a requested change is unresolved. Do not merge it."
|
||||
},
|
||||
{
|
||||
"title": "Clean only temporary resources",
|
||||
"body": "Remove disposable test guests, files and test backups created for this work. Preserve the app instance the user asked to keep, its data, and all unrelated guests and backups. Verify the cleanup against the test VMIDs recorded for this run."
|
||||
},
|
||||
{
|
||||
"title": "Report the handoff",
|
||||
"body": "Give the user the working app address or connection details, the pull request link, checks and CI results actually observed, temporary resources removed, and any limitations. Never include secrets in the pull request or final report."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -117,6 +117,7 @@
|
||||
{ "label": "Data, paths and networking", "href": "/docs/oci-manager/storage-network", "tail": "container disks, host directories, Rclone mounts and addresses." },
|
||||
{ "label": "Devices and acceleration", "href": "/docs/oci-manager/hardware", "tail": "GPU, NVIDIA, Coral, USB and other devices." },
|
||||
{ "label": "Multi-container applications", "href": "/docs/oci-manager/stacks", "tail": "application, database and cache as coordinated LXCs." },
|
||||
{ "label": "Install an app and contribute it", "href": "/docs/oci-manager/contribute-app", "tail": "agent brief, installation checks and catalog pull request." },
|
||||
{ "label": "Install, update and modify", "href": "/docs/oci-manager/lifecycle", "tail": "the instance contract and its operations." },
|
||||
{ "label": "In ProxMenux Monitor", "href": "/docs/oci-manager/monitor", "tail": "versions, updates, console output and terminal." }
|
||||
]
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Datos, rutas y red",
|
||||
"ociHardware": "Dispositivos y aceleración",
|
||||
"ociStacks": "Aplicaciones multicontenedor",
|
||||
"ociContributeApp": "Instalar una aplicación y proponerla al catálogo",
|
||||
"ociLifecycle": "Instalar, actualizar y modificar",
|
||||
"ociMonitor": "En ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Instalar una aplicación y añadirla al catálogo OCI | ProxMenux",
|
||||
"description": "Instrucciones reutilizables para un agente: instalar una aplicación con OCI manager Apps, comprobarla y preparar una propuesta para el catálogo de todos."
|
||||
},
|
||||
"header": {
|
||||
"title": "Instalar una aplicación y añadirla al catálogo OCI",
|
||||
"description": "Una guía práctica para pedirle a tu agente que instale la aplicación que quieres, la compruebe en tu propio sistema Proxmox y prepare una entrada reutilizable para el catálogo OCI de ProxMenux.",
|
||||
"section": "OCI manager Apps"
|
||||
},
|
||||
"sections": [
|
||||
{
|
||||
"id": "purpose",
|
||||
"title": "Una petición, dos resultados",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Usa esta guía cuando quieras que un agente instale una aplicación autoalojada en el sistema Proxmox que elijas y la proponga para el catálogo OCI de ProxMenux. Está pensada para distintos usuarios, equipos Proxmox, arquitecturas de CPU, sistemas de almacenamiento y dispositivos. No presupone que tengas un ordenador o un homelab concretos."
|
||||
},
|
||||
{
|
||||
"cards": {
|
||||
"items": [
|
||||
{
|
||||
"icon": "server",
|
||||
"title": "Tu aplicación",
|
||||
"body": "El agente instala y comprueba el servicio en el sistema Proxmox que hayas seleccionado. Debe conservar esta instancia y sus datos, salvo que le pidas que los elimine."
|
||||
},
|
||||
{
|
||||
"icon": "boxes",
|
||||
"title": "La entrada del catálogo",
|
||||
"body": "El agente revisa la imagen original, escribe su oci-compose, lo prueba hasta donde permita el sistema disponible y prepara un pull request para otros usuarios de ProxMenux."
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutWarning": {
|
||||
"title": "Una prueba en un sistema no demuestra compatibilidad con todos",
|
||||
"body": "El agente debe identificar la versión de Proxmox, la arquitectura de CPU, el almacenamiento, la red y los dispositivos disponibles. Debe indicar qué combinaciones ha probado. No puede dar por compatible otra arquitectura, GPU, NPU, dispositivo USB o tipo de almacenamiento basándose en una suposición."
|
||||
}
|
||||
},
|
||||
{
|
||||
"p": "Una entrada del catálogo no aparece automáticamente como verificada, con una ✓ en las listas del instalador. Esa marca se concede mediante el <validation>proceso de validación independiente del proyecto</validation>. Descargar la imagen o arrancar el contenedor no basta para afirmar que la aplicación funciona."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "brief",
|
||||
"title": "Copia estas instrucciones para tu agente",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Sustituye los datos entre corchetes si los conoces. El agente debe inspeccionar el Proxmox seleccionado y el estado actual del repositorio para averiguar el resto, y consultarte si necesita que tomes alguna decisión."
|
||||
},
|
||||
{
|
||||
"agentPrompt": {
|
||||
"title": "Petición reutilizable",
|
||||
"body": "Quiero instalar [NOMBRE DE LA APLICACIÓN] en el sistema Proxmox que seleccione, usando OCI manager Apps. Si la aplicación encaja, también quiero que prepares una contribución al catálogo OCI de ProxMenux para que otros usuarios puedan instalarla.\n\nProyecto o imagen original (si lo sé): [ENLACE O NO LO SÉ]\nSistema Proxmox que debes usar: [EQUIPO SELECCIONADO O NO LO SÉ]\nRequisitos especiales (si los conozco): [DATOS, RED, GPU/USB, HTTPS O NINGUNO]\n\nSigue estos pasos:\n1. Inspecciona el equipo Proxmox seleccionado e indica su versión de Proxmox VE, arquitectura, almacenamiento disponible, opciones de red y dispositivos relevantes. No presupongas una arquitectura ni un hardware concretos.\n2. Revisa el proyecto y la imagen originales, el catálogo actual de ProxMenux, los pull requests abiertos y las indicaciones recientes de los responsables. No añadas una aplicación duplicada. Las aplicaciones se proponen para el catálogo en la discusión #440 (https://github.com/MacRimi/ProxMenux/discussions/440): si aún no está, proponla con su imagen, el registro donde se publica y su categoría. El catálogo usa la imagen publicada por los desarrolladores cuando existe; atribuye correctamente a quien la publica.\n3. Instala la aplicación que he pedido mediante OCI manager Apps. Antes de confirmar, revisa la imagen, los recursos, las rutas de datos, la red y las variables. Protege los servicios y datos existentes. Deja instalada esta aplicación después de las pruebas, salvo que te pida que la elimines.\n4. Comprueba que el servicio responde de verdad y que funciona el acceso o la configuración inicial. Registra lo que hayas observado y no afirmes que funcionan características que no hayas probado.\n5. Escribe el oci-compose de la entrada del catálogo, siguiendo oci/README.md y los ficheros de oci/examples/, y prepara su icono. Si la aplicación requiere varios servicios, representa y prueba toda la pila siguiendo el mecanismo actual de ProxMenux; no omitas las bases de datos, cachés o redes internas que necesite.\n6. Ejecuta las comprobaciones del repositorio, incluida `cd oci && python3 -m unittest discover -s tests -p 'test_*.py'` con un usuario sin privilegios sobre una copia del repositorio, nunca en un host de producción, además de las comprobaciones pertinentes del catálogo, la documentación y las traducciones sin conexión. Corrige los fallos causados por este cambio y vuelve a ejecutar las comprobaciones.\n7. Valida la entrada candidata con instalaciones temporales cuando sea posible. No uses mi aplicación ni sus datos para probar actualizaciones destructivas, restauraciones o eliminaciones. Indica con honestidad el hardware que no esté disponible y las pruebas que no se hayan hecho.\n8. Prepara un pull request centrado en esta aplicación, con su nombre, imagen, icono, resultados breves y limitaciones, y adjunta el oci-compose probado a la propuesta de la discusión #440. Comprueba los resultados obligatorios de CI y los comentarios de los responsables. No integres el pull request.\n9. Elimina únicamente los CT temporales, archivos y backups de prueba que hayas creado para este trabajo. Conserva la aplicación que he pedido, sus datos y todas las VM, CT y backups ajenos a estas pruebas.\n\nAntes de hacer un cambio irreversible, publicar el servicio en Internet o borrar algo que pueda contener mis datos, detente y consúltame. No incluyas contraseñas, tokens ni configuración privada en el repositorio o el pull request. Al terminar, dame la dirección o los datos de acceso a la aplicación, el enlace al pull request, las comprobaciones observadas, lo que hayas limpiado y las limitaciones pendientes."
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutTip": {
|
||||
"title": "Mantén las credenciales en privado",
|
||||
"body": "Introduce las credenciales del registro y los secretos de la aplicación únicamente en la interfaz local correspondiente. El catálogo, las capturas, los registros y el pull request deben ocultar esos valores; nunca incluyas contraseñas ni tokens reales."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "research",
|
||||
"title": "Qué debe averiguar primero el agente",
|
||||
"blocks": [
|
||||
{
|
||||
"steps": {
|
||||
"items": [
|
||||
{
|
||||
"title": "Revisar el equipo seleccionado",
|
||||
"body": "Anota la versión de Proxmox VE y la arquitectura del equipo. Identifica el almacenamiento, los puentes de red, la asignación de direcciones y los dispositivos GPU, NPU o USB pertinentes. Comprueba el manifiesto de la imagen para esa arquitectura. Que exista un manifiesto amd64 no demuestra que también haya compatibilidad con arm64, ni al revés."
|
||||
},
|
||||
{
|
||||
"title": "Revisar la aplicación y el catálogo",
|
||||
"body": "Lee la documentación y el ejemplo de instalación de los desarrolladores. Consulta las <proposals>propuestas para el catálogo OCI</proposals>, la <roadmap>hoja de ruta</roadmap>, el <catalog>catálogo</catalog> y los pull requests abiertos para detectar duplicados o decisiones recientes, y propón allí primero la aplicación. El catálogo usa la imagen de los desarrolladores cuando existe; si hace falta una imagen de la comunidad, comprueba quién la mantiene e indica claramente quién la publica."
|
||||
},
|
||||
{
|
||||
"title": "Entender toda la instalación",
|
||||
"body": "Anota las imágenes, los comandos, los puertos, las variables, los volúmenes, el usuario y sus permisos, las comprobaciones de estado, el primer arranque, las credenciales, las dependencias y el hardware opcional. Si la aplicación usa varios servicios, incluye las bases de datos, la caché y la red interna que necesite. No descartes sin avisar ninguna opción de Compose que no tenga una equivalencia segura en Proxmox."
|
||||
},
|
||||
{
|
||||
"title": "Resolver la imagen",
|
||||
"body": "Usa el flujo Skopeo de OCI manager Apps para resolver y descargar la imagen y verificar sus capas. Si falla, identifica la causa real: credenciales, imagen o etiqueta inexistente, arquitectura no compatible, problemas de red o límite de peticiones del registro."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "install",
|
||||
"title": "Instalar y comprobar la aplicación que has pedido",
|
||||
"blocks": [
|
||||
{
|
||||
"list": {
|
||||
"items": [
|
||||
"Usa OCI manager Apps para instalarla. Cuando corresponda, elige un VMID de prueba libre y configura el almacenamiento, el puente de red, la dirección y los recursos según el equipo seleccionado y la petición del usuario.",
|
||||
"Antes de confirmar, revisa la imagen, los recursos, las rutas persistentes, la red y las variables. Mantén ocultos los secretos. En la instalación avanzada, compara el VMID, la CPU, la RAM, el almacenamiento, el puente de red, las variables y los dispositivos seleccionados con el `pct config` resultante.",
|
||||
"Usa el método de credenciales que proporcione la aplicación: las introduce el usuario, las genera el instalador, aparecen en el primer arranque o están documentadas por la imagen. Comprueba que funcionan y ocúltalas en las evidencias.",
|
||||
"Comprueba el servicio real. Si es una aplicación web, abre la URL indicada y confirma que carga la página o el acceso. Si no es web, verifica el protocolo y el puerto previstos. Usa HTTPS o un proxy inverso solo si hace falta para la prueba o instalación solicitada.",
|
||||
"Cuando el instalador ofrezca ambas opciones, prueba los volúmenes gestionados por Proxmox y los directorios del host. Crea datos desde la aplicación y comprueba que se guardan en la ruta prevista y tienen los permisos necesarios.",
|
||||
"Reinicia la aplicación o la pila y confirma que vuelve a arrancar con los datos y las credenciales. Prueba solo el hardware disponible; si falta algún dispositivo, indícalo y deja sin verificar esa integración."
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutDanger": {
|
||||
"title": "Protege la instalación que el usuario quiere conservar",
|
||||
"body": "Restaurar backups, probar la reversión de una imagen defectuosa y eliminar una aplicación pueden ser acciones destructivas. Haz esas pruebas en instancias temporales independientes, o con un plan explícito que proteja la instalación solicitada y sus datos. No elimines la aplicación del usuario como parte de la limpieza rutinaria."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "catalog",
|
||||
"title": "Preparar y validar la entrada del catálogo",
|
||||
"blocks": [
|
||||
{
|
||||
"list": {
|
||||
"items": [
|
||||
"Sigue la guía del oci-compose en <readme>oci/README.md</readme> y los ficheros de `oci/examples/`. Añade un ID único, categoría correcta, atribución al proyecto original, enlaces a la documentación, arquitecturas compatibles, referencia de imagen correcta e icono de la aplicación. Comprueba que el icono corresponde a esa aplicación y se muestra bien.",
|
||||
"Respeta el arranque, los puertos, las variables y las rutas persistentes de la imagen. Marca los secretos como sensibles. Define la propiedad y los permisos de los datos según la documentación original, no por intuición.",
|
||||
"Elige valores predeterminados prudentes y ofrece las opciones adicionales de forma clara. Indica compatibilidad con GPU, NPU, USB o arquitecturas solo cuando el flujo actual de ProxMenux lo admita y estén documentados sus requisitos.",
|
||||
"Incluye todos los servicios necesarios de una aplicación con varias imágenes y conserva las dependencias, la red privada, las comprobaciones de estado, las rutas persistentes y las operaciones coordinadas. Si la pila es compleja o requiere cambios comunes al motor, sepárala cuando así sea más fácil revisarla.",
|
||||
"Ejecuta toda la batería de pruebas del motor OCI con un usuario sin privilegios sobre una copia del repositorio, aunque CI no la ejecute. Lanza las comprobaciones pertinentes del esquema, el catálogo, la documentación, i18n y el registro de validación. No edites a mano la página generada `oci/VALIDATION.md`: la regenera `python3 .github/scripts/oci_validation.py render`."
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"shell": {
|
||||
"code": "cd oci && python3 -m unittest discover -s tests -p 'test_*.py'"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "lifecycle",
|
||||
"title": "Pruebas del ciclo de vida en una instalación temporal",
|
||||
"blocks": [
|
||||
{
|
||||
"p": "Usa una instancia temporal independiente para probar operaciones que actualicen, restauren o eliminen la aplicación. Prueba las opciones que admita la aplicación y el equipo disponible. Para cada punto, indica PASS, FAIL, BLOCKED, NOT APPLICABLE o NOT TESTED e incluye una evidencia observable."
|
||||
},
|
||||
{
|
||||
"table": {
|
||||
"headers": [
|
||||
"Prueba",
|
||||
"Qué se considera correcto"
|
||||
],
|
||||
"rows": [
|
||||
[
|
||||
"Descarga de la imagen",
|
||||
"Skopeo resuelve la referencia prevista y verifica las capas. Si falla, se identifica la causa."
|
||||
],
|
||||
[
|
||||
"Instalación predeterminada",
|
||||
"El resumen de confirmación es correcto; el LXC o la pila arranca, obtiene conectividad de red y supera las comprobaciones del primer arranque."
|
||||
],
|
||||
[
|
||||
"Configuración avanzada",
|
||||
"El VMID, la CPU, la RAM, el almacenamiento, el puente de red, las variables y los dispositivos compatibles coinciden con la configuración guardada en Proxmox."
|
||||
],
|
||||
[
|
||||
"Credenciales y respuesta",
|
||||
"Funcionan las credenciales mostradas o configuradas. Carga la web o el acceso, o responde el servicio no web esperado."
|
||||
],
|
||||
[
|
||||
"Datos persistentes",
|
||||
"Las opciones de almacenamiento gestionado y directorio del host se comportan como indica la documentación; los datos sobreviven al reinicio con los permisos correctos."
|
||||
],
|
||||
[
|
||||
"Reinicio",
|
||||
"La aplicación o la pila arranca automáticamente y conserva sus datos y configuración."
|
||||
],
|
||||
[
|
||||
"Backup y restauración",
|
||||
"Un backup de Proxmox restaurado en otro VMID temporal arranca, responde y aparece en Gestionar aplicaciones OCI instaladas."
|
||||
],
|
||||
[
|
||||
"Actualización y reversión",
|
||||
"La actualización de la imagen conserva los datos, las credenciales, la red, los dispositivos y la configuración de Proxmox. Prueba la reversión si es seguro; si no, indica NOT TESTED."
|
||||
],
|
||||
[
|
||||
"Modificación",
|
||||
"Se aplica una opción compatible, se conservan las demás y la aplicación sigue respondiendo. Los cambios que no afectan a la imagen no deberían descargarla de nuevo ni recrear la aplicación innecesariamente."
|
||||
],
|
||||
[
|
||||
"Eliminación",
|
||||
"Gestionar aplicaciones OCI instaladas elimina los LXC temporales, sus discos y sus registros. Los directorios de datos del host se conservan. Elimina solo los backups de VMID temporales de prueba."
|
||||
]
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"calloutInfo": {
|
||||
"title": "Indica claramente las limitaciones de hardware",
|
||||
"body": "Si la interfaz de la aplicación arranca pero falta una cámara, coordinador, GPU, NPU o dispositivo USB opcional, puede darse por aprobada la comprobación de la interfaz mientras la integración de hardware sigue NOT TESTED. Indica qué dispositivo y capacidad del equipo hacen falta."
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "pr",
|
||||
"title": "Preparar el pull request y entregar el resultado",
|
||||
"blocks": [
|
||||
{
|
||||
"steps": {
|
||||
"items": [
|
||||
{
|
||||
"title": "Detallar lo que se ha probado de verdad",
|
||||
"body": "Incluye el nombre de la aplicación, el ID del catálogo, la imagen y su digest, la versión de Proxmox VE, la arquitectura, el modo de instalación, el almacenamiento, la red, los dispositivos y la comprobación real de respuesta. Resume los resultados del ciclo de vida e indica los casos bloqueados, no disponibles y no probados. Añade el icono y el resultado de las pruebas del motor OCI."
|
||||
},
|
||||
{
|
||||
"title": "Revisar los comentarios del proyecto",
|
||||
"body": "Después de abrir el pull request, revisa todas las comprobaciones obligatorias de CI en su versión más reciente. Lee los comentarios y revisiones de los responsables, aplica los cambios que pidan y vuelve a ejecutar las comprobaciones afectadas. No digas que está listo si falla una prueba obligatoria o queda pendiente un cambio solicitado. No lo integres."
|
||||
},
|
||||
{
|
||||
"title": "Limpiar solo los recursos temporales",
|
||||
"body": "Elimina los CT, archivos y backups temporales creados para estas pruebas. Conserva la aplicación que el usuario quería instalar, sus datos y todas las VM, CT y backups ajenos a la prueba. Verifica la limpieza usando los VMID temporales anotados para esta ejecución."
|
||||
},
|
||||
{
|
||||
"title": "Entregar el resultado",
|
||||
"body": "Dale al usuario la dirección o los datos de acceso a la aplicación, el enlace al pull request, las comprobaciones y resultados de CI que hayas observado, los recursos temporales eliminados y las limitaciones pendientes. No incluyas secretos en el pull request ni en el informe final."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Aplicación, base de datos y caché en varios LXC coordinados."
|
||||
},
|
||||
{
|
||||
"label": "Instalar una aplicación y proponerla al catálogo",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "instrucciones para el agente, pruebas y pull request."
|
||||
},
|
||||
{
|
||||
"label": "Instalar, actualizar y modificar",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Données, chemins et réseau",
|
||||
"ociHardware": "Périphériques et accélération",
|
||||
"ociStacks": "Applications à plusieurs conteneurs",
|
||||
"ociContributeApp": "Installer une application et contribuer au catalogue",
|
||||
"ociLifecycle": "Installer, mettre à jour et modifier",
|
||||
"ociMonitor": "Dans ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Application, base de données et cache dans des LXC coordonnés."
|
||||
},
|
||||
{
|
||||
"label": "Installer une application et contribuer au catalogue",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "instructions pour l’agent, tests et demande de fusion."
|
||||
},
|
||||
{
|
||||
"label": "Installer, mettre à jour et modifier",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Dati, percorsi e rete",
|
||||
"ociHardware": "Dispositivi e accelerazione",
|
||||
"ociStacks": "Applicazioni con più container",
|
||||
"ociContributeApp": "Installare un’app e proporla al catalogo",
|
||||
"ociLifecycle": "Installazione, aggiornamento e modifica",
|
||||
"ociMonitor": "In ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Applicazione, database e cache in LXC coordinati."
|
||||
},
|
||||
{
|
||||
"label": "Installare un’app e proporla al catalogo",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "istruzioni per l’agente, verifiche e pull request."
|
||||
},
|
||||
{
|
||||
"label": "Installazione, aggiornamento e modifica",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Dados, caminhos e rede",
|
||||
"ociHardware": "Dispositivos e aceleração",
|
||||
"ociStacks": "Aplicações com vários contentores",
|
||||
"ociContributeApp": "Instalar uma aplicação e contribuir para o catálogo",
|
||||
"ociLifecycle": "Instalar, atualizar e modificar",
|
||||
"ociMonitor": "No ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Aplicação, base de dados e cache em LXC coordenados."
|
||||
},
|
||||
{
|
||||
"label": "Instalar uma aplicação e contribuir para o catálogo",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "instruções para o agente, testes e pull request."
|
||||
},
|
||||
{
|
||||
"label": "Instalar, atualizar e modificar",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -86,6 +86,7 @@
|
||||
"ociStorageNetwork": "Dáta, cesty a sieť",
|
||||
"ociHardware": "Zariadenia a akcelerácia",
|
||||
"ociStacks": "Aplikácie s viacerými kontajnermi",
|
||||
"ociContributeApp": "Nainštalovať aplikáciu a pridať ju do katalógu",
|
||||
"ociLifecycle": "Inštalácia, aktualizácia a vytvorenie znova",
|
||||
"ociMonitor": "V ProxMenux Monitore",
|
||||
"proxmenuxScripts": "Skripty ProxMenux",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Aplikácia, databáza a vyrovnávacia pamäť v koordinovaných LXC."
|
||||
},
|
||||
{
|
||||
"label": "Nainštalovať aplikáciu a pridať ju do katalógu",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "pokyny pre agenta, testy a príspevok do katalógu."
|
||||
},
|
||||
{
|
||||
"label": "Inštalácia, aktualizácia a úpravy",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
@@ -94,6 +94,7 @@
|
||||
"ociStorageNetwork": "Data, sökvägar och nätverk",
|
||||
"ociHardware": "Enheter och acceleration",
|
||||
"ociStacks": "Program med flera containrar",
|
||||
"ociContributeApp": "Installera en app och bidra till katalogen",
|
||||
"ociLifecycle": "Installera, uppdatera och ändra",
|
||||
"ociMonitor": "I ProxMenux Monitor",
|
||||
"proxmenuxScripts": "ProxMenux Scripts",
|
||||
|
||||
@@ -194,6 +194,11 @@
|
||||
"href": "/docs/oci-manager/stacks",
|
||||
"tail": "Program, databas och cache i samordnade LXC-containrar."
|
||||
},
|
||||
{
|
||||
"label": "Installera en app och bidra till katalogen",
|
||||
"href": "/docs/oci-manager/contribute-app",
|
||||
"tail": "instruktioner för agenten, tester och katalogförslag."
|
||||
},
|
||||
{
|
||||
"label": "Installera, uppdatera och ändra",
|
||||
"href": "/docs/oci-manager/lifecycle",
|
||||
|
||||
Reference in New Issue
Block a user