1Panel Appstore Skills

Package Dockerized applications into the 1Panel appstore/local-app format. Use official application sources for installation details and generate the app package from an intermediate spec.

Workflow

1. Resolve the application source:
   • Repository URL: use the provided repository as the primary source.
   • App name only: search mainstream open-source code hosts and confirm the official repository.
   • Docker image or Compose file: collect the missing app metadata from official docs or the user.
2. Inspect official files/docs for Docker image, Compose topology, ports, volumes, environment variables, runtime user, README content, website, docs, logo, and version.
3. Read only the references needed:
   • references/source-policy.md before resolving Docker install details from an app name or repository URL.
   • references/appstore-format.md for 1Panel package rules.
   • references/appspec.md before writing the intermediate spec.
   • references/review-checklist.md before final handoff when you need a packaging checklist.
4. Write an intermediate JSON spec, usually under /tmp/<app-key>-1panel-appspec.json or a task-specific output directory.
5. Run scripts/generate_app_package.py --spec <spec.json> --output <output-dir> to create the package.
6. Return the package path, generated version, source evidence, warnings, and local testing path.

Source Rules

• Never invent Docker installation details. Docker image, ports, volumes, environment variables, dependencies, and runtime user must come from the official repository or official docs.
• If the user provides a repository URL, do not switch sources unless that repository links to official docs needed for Docker installation.
• If only an app name is provided, confirm the official repository before packaging. If it cannot be confirmed, ask for the repository URL.
• Do not use third-party tutorials, unrelated Docker Hub pages, mirrors, or guessed Compose snippets.
• Prefer official container images. Use a third-party image only when the official project has no public image or only documents source builds, the user explicitly accepts the third-party image, and the third-party image page or source repository clearly identifies the upstream project.
• Always generate Docker-based packages. If no reliable containerization path exists, stop and state what is missing.

Package Rules

• Prefer a single primary service when possible. For secondary services, use explicit names and make sure every service joins 1panel-network.
• Use ${CONTAINER_NAME} for the primary service container name. Use ${CONTAINER_NAME}-<service> for secondary service container names.
• Use PANEL_APP_PORT_HTTP for the primary web port. Use PANEL_APP_PORT_<PURPOSE> for additional ports.
• Every ${...} variable in docker-compose.yml must be declared in version data.yml, except known 1Panel-provided values such as ${CONTAINER_NAME} and service-derived ${PANEL_DB_PORT}.
• Put user-editable settings in version data.yml form fields. Use password fields for secrets.
• Keep persistent data mounts relative, for example ./data:/app/data.
• Keep generated changes scoped to the app package or skill resources requested by the user.

README and I18n

• Generate root README.md in the concise existing appstore style: ## 产品介绍 and, when useful, ## 主要功能. Generate README_en.md with ## Introduction and ## Features when the upstream application website, repository README, or app UI supports English.
• Do not put generated-package diagnostics, source evidence, local testing instructions, or long operational notes in app README files. Keep those in the final response or intermediate spec.
• Fill i18n maps for root additionalProperties.description and every version data.yml form field label. Use the appstore language set en, es-es, ja, ms, pt-br, ru, ko, zh-Hant, zh, and tr.
• Reuse translations already present in existing apps for common labels such as Port, HTTP Port, Web UI Port, Password, API Key, Token, Model, Provider, and Base URL. Do not invent specialized translations when no reliable source or existing pattern exists; prefer a clear English fallback and call out the assumption.

init.sh Rules

• For every persistent relative volume, check whether the container runs as a non-root built-in user. Use official Dockerfile USER, official Compose user:, image docs, or installation docs as evidence. If the mounted directory must be writable by a non-root UID/GID, add an init_permissions or service volume_permissions entry so scripts/init.sh fixes ownership before startup.
• init.sh content must be based on official application sources. Use init_source_evidence to record the official file or documentation that supports every generated init action.
• Besides persistent directory permissions, add other init_commands only when official install docs require a host-side preflight step. Keep the script minimal.
• Do not guess UID/GID values. If the official source does not reveal the runtime user and the app is known to fail on host-mounted volumes, stop and ask the user for the intended UID/GID or official container docs.
• Let the package tree create persistent directories with .gitkeep; use init.sh to change permissions, not as the primary way to create expected directories.
• If no init action is needed, do not generate scripts/ or scripts/init.sh.

Scripts

• scripts/generate_app_package.py
  • Input: JSON app spec.
  • Output: apps/<key>/data.yml, README.md, README_en.md when applicable, logo.png, <version>/data.yml, <version>/docker-compose.yml, and data directories.
  • Use this instead of hand-writing package files when starting a new app package.
• scripts/validate_app_package.py
  • Optional helper for basic generated-package checks.
  • Do not present it as a full 1Panel appstore review or runtime installation test.

Output Contract

When done, report:

• App package path.
• Generated version.
• Source evidence used for Docker installation details.
• Any warnings or assumptions.
• Local test target: /opt/1panel/resource/apps/local/<app-key>.