1panel-app-builder: Скилл для создания приложений 1Panel

--- name: 1panel-app-builder description: > Build 1Panel local app store configurations from Docker deployments. Use when: - User provides a GitHub project link and wants to add it to 1Panel app store - User has a docker-compose.yml or docker run command and needs 1Panel app format - User wants to create a local app for 1Panel panel - User mentions "1Panel app", "1Panel 应用商店", "本地应用", "app store", or similar Supports: GitHub repos, Docker Hub images, docker-compose files, docker run commands. Output: Complete app folder with data.yml, docker-compose.yml, logo.png, README.md Always use this skill for 1Panel app packaging - it knows the exact directory structure, variable naming conventions (PANEL_APP_PORT_HTTP, CONTAINER_NAME), and 1panel-network requirements that are easy to get wrong without guidance. --- # 1Panel App Store Builder Transform Docker deployments into 1Panel-compatible local app store packages. ## Understanding 1Panel App Structure A valid 1Panel app follows this directory structure: ``` app-key/ # App identifier (lowercase, hyphenated) ├── logo.png # App icon (64x64 or 128x128 recommended) ├── data.yml # App metadata (top-level) ├── README.md # Chinese documentation ├── README_en.md # English documentation (optional) └── 1.0.0/ # Version directory (semver or "latest") ├── data.yml # Parameter definitions (form fields) ├── docker-compose.yml # Compose file with variable substitution ├── data/ # Persistent data directory └── scripts/ # Optional scripts └── upgrade.sh # Upgrade script ``` ## Step-by-Step Workflow ### Step 1: Gather Source Information Based on user input type, extract Docker deployment details: **From GitHub Link:** 1. Fetch the GitHub repository README.md 2. Look for Docker installation instructions (docker run, docker-compose) 3. Extract: image name, ports, volumes, environment variables 4. Note: project name, description, official website, supported architectures **From docker-compose.yml:** 1. Parse all services defined 2. Extract: image versions, port mappings, volume mounts, environment variables 3. Identify the main service (typically the one with web UI) **From docker run command:** 1. Parse flags: `-p` (ports), `-v` (volumes), `-e` (env vars), `--name` 2. Extract the image name and tag 3. Identify exposed ports and data directories ### Step 2: Resolve Latest Version (Create Version + latest) Always create **two** version directories when possible: - `latest/` uses image tag `latest` - `<version>/` uses the **latest concrete tag** from the registry **How to resolve the latest concrete tag:** 1. If the image is on **GitHub Container Registry** (`ghcr.io`), query tags from GitHub Packages (GHCR). 2. Otherwise, query **Docker Hub** tags. 3. Prefer the newest semver-like tag (e.g., `v1.2.3` or `1.2.3`). If none exist, pick the most recently updated non-`latest` tag. 4. If you cannot resolve a concrete tag, fall back to the image tag from input and warn the user. **Rule:** The `latest/` directory must **always** use `image: ...:latest`. The `<version>/` directory must **always** use `image: ...:<version>`. ### Step 3: Generate App Key and Metadata **App Key Rules:** - Lowercase only - Use hyphens for multi-word names - Keep it short but descriptive - Examples: `alist`, `it-tools`, `n8n-zh`, `lobe-chat-data` **Required Metadata (top-level data.yml):** ```yaml name: AppName # Display name (can have capitals) tags: # Chinese tags for categorization - 开发工具 - 实用工具 title: Brief Chinese description description: Same as title additionalProperties: key: app-key # Must match directory name name: AppName # Same as name above tags: # English tags - DevTool - Utility shortDescZh: Chinese description shortDescEn: English description description: en: Full English description zh: Full Chinese description # Add more languages if available: ja, ko, ru, pt-br, ms, zh-Hant type: website # or "runtime" for databases, "tool" for CLI tools crossVersionUpdate: true # Usually true limit: 0 # 0 = unlimited instances recommend: 0 # 0-100, higher = more recommended website: https://example.com # Official website github: https://github.com/org/repo document: https://docs.example.com architectures: # Supported CPU architectures - amd64 - arm64 # Add: arm/v7, arm/v6, s390x if supported ``` ### Step 4: Define Parameters (version/data.yml) Parameters become UI form fields in 1Panel. Define user-configurable values: ```yaml additionalProperties: formFields: # Port parameter example - default: 8080 edit: true envKey: PANEL_APP_PORT_HTTP # Variable name used in docker-compose labelEn: Web Port labelZh: Web端口 required: true rule: paramPort # Validation rule type: number # Field type label: # Multi-language labels en: Web Port zh: Web端口 ja: Webポート ko: Web 포트 # Text parameter example (for API keys, passwords, etc.) - default: "" edit: true envKey: API_KEY labelEn: API Key labelZh: API密钥 required: false rule: paramCommon type: text # Password parameter example - default: "changeme" edit: true envKey: ADMIN_PASSWORD labelEn: Admin Password labelZh: 管理员密码 required: true rule: paramCommon type: password # Select parameter example - default: "sqlite" edit: true envKey: DATABASE_TYPE labelEn: Database Type labelZh: 数据库类型 required: true type: select values: - label: SQLite value: sqlite - label: PostgreSQL value: postgres ``` **Parameter Types:** - `number`: For ports, counts - `text`: For API keys, URLs, names - `password`: For secrets (masked input) - `select`: For dropdown choices - `boolean`: For toggle switches **Validation Rules:** - `paramPort`: Valid port number (1-65535) - `paramCommon`: Non-empty string - `paramExtUrl`: Valid URL format - Empty string: No validation ### Port envKey Naming (Use 1Panel Standard Names) Prefer these **standard** `envKey` names (observed across apps in `apps/`): - `PANEL_APP_PORT_HTTP` (primary Web/UI port) - `PANEL_APP_PORT_HTTPS` - `PANEL_APP_PORT_API` - `PANEL_APP_PORT_ADMIN` - `PANEL_APP_PORT_PROXY` - `PANEL_APP_PORT_PROXY_HTTP` - `PANEL_APP_PORT_PROXY_HTTPS` - `PANEL_APP_PORT_DB` - `PANEL_APP_PORT_SSH` - `PANEL_APP_PORT_S3` - `PANEL_APP_PORT_SYNC` **Guideline:** Use the most semantically correct name first; only invent new suffixes if none of the standard names fit. ### Step 5: Create docker-compose.yml Convert the original Docker deployment to use variable substitution: ```yaml services: app-name: container_name: ${CONTAINER_NAME} restart: always networks: - 1panel-network ports: - "${PANEL_APP_PORT_HTTP}:8080" volumes: - ./data:/app/data environment: - TZ=Asia/Shanghai image: org/image:tag labels: createdBy: "Apps" networks: 1panel-network: external: true ``` **Critical Rules:** 1. Always use `${CONTAINER_NAME}` for container_name 2. Always use `restart: always` 3. Always connect to `1panel-network` (external network) 4. Port mapping uses `PANEL_APP_PORT_*` variables from version/data.yml 5. Volume paths use relative `./data/` for persistence 6. Add `labels: createdBy: "Apps"` 7. Keep original environment variables but use defaults **Port Mapping Format (Important):** Use quoted mappings like: ``` - "${PANEL_APP_PORT_HTTP}:8080" ``` and ensure the same `envKey` exists in `version/data.yml`. ### Step 6: Create README Files **README.md (Chinese):** ```markdown # AppName 简短描述应用的功能和特点。 ## 功能特点 - 特点1 - 特点2 - 特点3 ## 使用说明 ### 默认端口 - Web界面: 8080 ### 默认账号密码 - 用户名: admin - 密码: changeme (请在部署后立即修改) ### 数据目录 应用数据存储在 `./data` 目录。 ## 相关链接 - 官方网站: https://example.com - GitHub: https://github.com/org/repo - 文档: https://docs.example.com ``` **README_en.md (English, optional):** ```markdown # AppName Brief description of the application. ## Features - Feature 1 - Feature 2 - Feature 3 ## Usage ### Default Port - Web UI: 8080 ### Default Credentials - Username: admin - Password: changeme (change after deployment) ## Links - Website: https://example.com - GitHub: https://github.com/org/repo ``` ### Step 7: Download App Icon **Priority order:** 1. **Search the GitHub repository** for common icon files (e.g., `logo.png`, `icon.png`, `assets/logo.png`, `.github/icon.png`). Use the repo's raw download URL if found. 2. If not found, search and download the app logo from these sources (in order): 1. **Dashboard Icons**: https://dashboardicons.com/icons?q={app-name} 2. **Simple Icons**: https://simpleicons.org/?q={app-name} 3. **Selfh.st Icons**: https://selfh.st/icons/ **Do not** create a placeholder or incorrect icon. If not found, warn and leave `logo.png` for manual replacement. ### Step 8: Create Data Directory Structure Create the `data/` directory inside the version folder: ```bash mkdir -p app-key/version/data ``` This directory will be mounted as a volume for persistent data. ## Quality Checklist Before delivering the app package, verify: - [ ] App key is lowercase with hyphens only - [ ] All required fields in top-level data.yml are present - [ ] `latest/` and `<version>/` directories both exist (when a concrete tag is resolvable) - [ ] `latest/` uses image tag `latest` - [ ] `<version>/` uses the concrete latest tag from registry - [ ] Version data.yml has proper parameter definitions (formFields) - [ ] docker-compose.yml uses variable substitution correctly - [ ] `1panel-network` is defined as external network - [ ] Volume paths use relative `./data/` format - [ ] README files are created with proper documentation - [ ] Logo file exists (logo.png) - [ ] Version directory follows semver; avoid only `latest` ## Common Patterns ### Database Applications ```yaml # For apps that need a database (PostgreSQL, MySQL, etc.) # Include database as a separate service in docker-compose services: app: depends_on: - db db: image: postgres:15 volumes: - ./data/db:/var/lib/postgresql/data environment: - POSTGRES_DB=appdb - POSTGRES_USER=appuser - POSTGRES_PASSWORD=${DB_PASSWORD} ``` ### Multi-Service Applications ```yaml # For apps with multiple services (frontend + backend, etc.) services: frontend: image: org/frontend:tag ports: - "${PANEL_APP_PORT_HTTP}:80" backend: image: org/backend:tag ports: - "${PANEL_APP_PORT_API}:8080" ``` ### Applications with Reverse Proxy ```yaml # For apps that don't expose ports directly services: app: # No ports section - accessed through 1Panel's reverse proxy expose: - "8080" networks: - 1panel-network ``` ## Automation Scripts Use the provided scripts for faster workflow: ### generate-app.sh - 自动生成应用配置 ```bash # GitHub 项目 ./scripts/generate-app.sh https://github.com/alist-org/alist # docker-compose 文件 ./scripts/generate-app.sh ./docker-compose.yml # docker run 命令 ./scripts/generate-app.sh "docker run -d --name=nginx -p 80:80 nginx:latest" ``` ### download-icon.sh - 下载应用图标 ```bash ./scripts/download-icon.sh redis ./logo.png 200 ``` ### validate-app.sh - 验证配置完整性 ```bash ./scripts/validate-app.sh ./apps/myapp ``` ## Reference Files - `references/1panel-examples.md` - 完整的真实应用配置示例（AList、NocoDB等） - `examples/example-usage.md` - 使用示例和工作流程 ## Troubleshooting **Issue**: App won't start - Check if ports are already in use - Verify volume permissions - Check container logs: `docker logs ${CONTAINER_NAME}` **Issue**: Data not persisting - Ensure volumes are correctly mapped to `./data/` - Check directory permissions **Issue**: Environment variables not working - Verify variable names match between data.yml and docker-compose.yml - Check default values are appropriate **Issue**: 图标下载失败 - 从以下网站手动下载： - https://dashboardicons.com/icons?q={app-name} - https://simpleicons.org/?q={app-name} - https://selfh.st/icons/