1Panel-Appstore AGENTS.md

Repository Guidelines

Project Shape

This repository is a third-party 1Panel local app store. It is mostly YAML, Docker Compose files, READMEs, icons, and helper shell scripts. There is no central application build step.

Top-level files:

• data.yaml: app store metadata and category/tag definitions.
• apps/<app-key>/: one app package per directory.
• skills/: app-generation guidance, templates, and helper scripts.
• update/: update-detection and README-version sync scripts.

App Package Layout

Use this structure for each app:

apps/<app-key>/
├── data.yml
├── logo.png
├── README.md
├── README_en.md
└── <version>/
    ├── data.yml
    ├── docker-compose.yml
    └── data/

Some apps also include latest/. When both latest/ and a concrete version exist, latest/ should use an image tagged latest, and the concrete version directory should use the pinned image tag.

1Panel Conventions

• App keys are lowercase and hyphenated, and must match the app directory name.
• Top-level apps/<app-key>/data.yml contains display metadata.
• Version-level data.yml contains additionalProperties.formFields.
• Prefer standard port variables such as PANEL_APP_PORT_HTTP, PANEL_APP_PORT_HTTPS, PANEL_APP_PORT_API, PANEL_APP_PORT_ADMIN, PANEL_APP_PORT_PROXY, PANEL_APP_PORT_DB, PANEL_APP_PORT_SSH, PANEL_APP_PORT_S3, and PANEL_APP_PORT_SYNC.
• Each PANEL_APP_PORT_* used in docker-compose.yml should have a matching form field in the version data.yml.
• Compose services should use container_name: ${CONTAINER_NAME}, restart: always, the external 1panel-network, relative ./data/ volume paths for persistence, and labels: createdBy: "Apps".
• Use ./data/... mounts instead of host absolute paths unless the app genuinely requires host integration.
• Keep app metadata tags aligned with data.yaml.

App Creation Workflow

Before adding or changing app packages, read skills/SKILL.md. It documents the expected 1Panel packaging workflow, metadata fields, compose conversion rules, README shape, and icon lookup order.