mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-11-02 19:02:31 +00:00
docs(oci): add reusable app catalog guide
This commit is contained in:
Jonatan
@@ -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 ProxMenux OCI Manager, 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, if the app is a good fit, contribute its recipe to 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, creates a reusable recipe, 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 recipe is not automatically marked <strong>Verified</strong>. That label 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 ProxMenux OCI Manager. 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. Prefer the developer's image and identify its publisher accurately.\n3. Install my requested app through ProxMenux OCI Manager. 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. Prepare the catalog recipe and 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`, 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. 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 <roadmap>roadmap</roadmap>, <catalog>catalog</catalog> and open pull requests for duplicates or current design decisions. Prefer a developer-published image; if a community image is needed, verify and name its publisher."
|
||||
},
|
||||
{
|
||||
"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 OCI Manager's Skopeo flow 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 ProxMenux OCI Manager 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 recipe",
|
||||
"blocks": [
|
||||
{
|
||||
"list": {
|
||||
"items": [
|
||||
"Follow the current catalog schema and a maintained example. 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 on Linux, 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."
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"shell": {
|
||||
"code": "cd oci && python3 -m unittest discover -s tests"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"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."
|
||||
],
|
||||
[
|
||||
"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 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." }
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user