ProxMenux/web/messages/en/docs/oci-manager/contribute-app.json

{
  "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."
              }
            ]
          }
        }
      ]
    }
  ]
}