mirror of
https://github.com/arch3rPro/1Panel-Appstore.git
synced 2026-06-11 00:59:40 +08:00
arch3rPro
100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|
|
|
|
Useful helper scripts:
|
|
|
|
```bash
|
|
cd /root/github/1Panel-Appstore/skills
|
|
./scripts/generate-app.sh <github-url-or-compose-or-docker-run>
|
|
./scripts/download-icon.sh <app-name> <output-path> 200
|
|
./scripts/validate-app.sh ../apps/<app-key>
|
|
```
|
|
|
|
The generator is a starting point. Review and adjust generated metadata,
|
|
ports, volumes, environment variables, README content, and icons before
|
|
considering the app complete.
|
|
|
|
## Validation
|
|
|
|
For a changed app, run:
|
|
|
|
```bash
|
|
cd /root/github/1Panel-Appstore
|
|
./skills/scripts/validate-app.sh ./apps/<app-key>
|
|
```
|
|
|
|
For YAML or Compose edits, also inspect the affected files directly. The
|
|
validator is shell/grep based and catches common structural problems, not every
|
|
semantic issue.
|
|
|
|
## Update Scripts
|
|
|
|
The scripts in `update/` may perform network requests and `git pull`. Do not run
|
|
them casually while making focused app edits. If using them, inspect the script
|
|
and current worktree first.
|
|
|
|
## Editing Notes
|
|
|
|
- Preserve existing YAML indentation style within the file being edited.
|
|
- Keep READMEs concise and app-focused; many apps include both Chinese and
|
|
English README files.
|
|
- Do not replace real logos with placeholders. If an icon cannot be found, call
|
|
that out instead of inventing an inaccurate asset.
|
|
- Treat unrelated changes in the worktree as user-owned and leave them alone.
|