1panel App Adapter

1Panel AppStore Adapter

Adapt Docker applications into reviewable 1Panel AppStore packages, then validate their structure, metadata, Compose configuration, localization, and upgrade behavior against source-backed rules.

Submission Target and Delivery Defaults

Use third-party by default. Select official only for an official 1Panel appstore submission, and pass --submission-profile official to generation, migration, import, and validation. Read references/submission-profiles.md for the exact file and form contract before choosing a route.

• Deliver only <out-dir>/<app-key>/. Keep source, license-review, registry, and test evidence outside it at <out-dir>/.evidence/<app-key>/source-evidence.json; pass --source-evidence <path> when validating a copied package.
• Third-party packages retain .env.sample and reviewed path choices. Official packages omit .env.sample; any existing directory form fields keep their source-backed defaults with disabled: true and edit: false. Neither mode changes the selected service graph or mount mechanism.
• Write Chinese README.md and English README_en.md with product features and usage. Follow references/readme-style.md. Do not put the selected application version, audit records, or generator diagnostics into product prose; document a necessary upgrade boundary only when it changes a user action.
• Add a lifecycle hook only for a concrete setup, reconciliation, migration, or cleanup operation. Prefer Compose and upstream entrypoints for ordinary startup. Do not build an extra startup framework, runtime package installer, secret generator, or generic supervisor without an exact upstream requirement. Preserve source-backed ownership and path confinement when they are needed.
• Do not generate application license text merely because an image is referenced. Ship only notices or sources required by material actually copied into the package. The fallback icon's MIT notice is included in the README, without an extra license text or SVG.

Start Here: Choose One Route

Work from the skill directory so every scripts/... and references/... path resolves. Read this SKILL.md through its final line. First classify the input, then follow exactly one route below. Open and read every reference named by that route through its final line before running its command, and state how the references affected the plan or artifact. Every route ends at Completion Gates. If official Docker deployment evidence is unavailable, stop and report the missing evidence; do not guess a package. Publishing is outside this skill.

1. New app from official Docker/Compose: Read references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md, then record the preflight decision before scaffolding. Stop for platform_stack_terminal; stop for specialized_conditional until every named prerequisite is proven. --out-dir is a parent: for example, run bash scripts/scaffold-v2.sh --app-key <app-key> --title <title> --image <image> --version <version> --out-dir "$RUN_ROOT/artifact" --source-repository <url> --source-docker-docs <url> --source-compose-file <url>, then require "$RUN_ROOT/artifact/<app-key>" to directly contain data.yml, README.md, README_en.md, and <version>/; external source-evidence.json is a sibling sidecar; reject <app-key>/<app-key>. Review every generated file against the authoritative Compose and replace all placeholders. For callback, origin, or other public URL fields, never synthesize localhost or 127.0.0.1: expose a required public URL as a required form field; leave an optional public URL empty or omit it and document the affected features.
2. AppSpec input: Read references/appspec.md, references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md. Run python3 scripts/generate-from-appspec.py --spec <appspec.json> --out-dir <out-dir> --validate --require-validate. Review the generated topology, variables, metadata, translations, lifecycle ledger, and validation report against the AppSpec and official sources.
3. Existing v1 or mixed package: Read references/source-policy.md, references/topology-preflight.md, references/upgrade-maintenance.md, and references/lifecycle-safety.md. Run bash scripts/migrate-v1-to-v2.sh --src <app-dir> --out <out-dir> [--version <source-version>] [--target-version <target-version>] --source-repository <url> --source-docker-docs <url> --source-compose-file <url>. Review the migrated root/version metadata, Compose, .env.sample, lifecycle scripts, and upgrade compatibility; source URL flags may be omitted only when the source package has valid external or historical in-package source-evidence.json.
4. aaPanel/Baota input: Read references/baota-migration-workflow.md, references/baota-app-format.md, references/baota-to-1panel-mapping.md, references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md. Precheck the complete prepared input with python3 scripts/import-baota-app.py --input <baota-app-dir> --precheck-only --report <report.json>; for a batch add --batch. Then convert one selected version per invocation with python3 scripts/import-baota-app.py --input <baota-app-dir> --out-dir <out-dir> --version <exact-version> --validate --require-validate. Review every output as converted_candidate against official upstream evidence; never infer version order from Baota metadata.
5. Update an existing v2 app: Read references/upgrade-maintenance.md, references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md. Compare the old and new package before editing; use only the needed helper commands below. Review image lineage, persisted data, changed variables, dependencies, lifecycle scripts, and direct-upgrade behavior, then run final validation.
6. Validate only: Read references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md; also read references/upgrade-maintenance.md when several versions or an update are involved. Start with bash scripts/validate-v2.sh --dir <app-dir> and review every failure and warning before strict validation. Validation does not authorize guessing or silently patching unknown semantics.
7. PHP runtime: Read references/php-runtime.md, references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md before choosing a generator. Follow the runtime-specific package shape, review picker metadata and actual runtime integration, then use the applicable helper commands and final validation below. Do not treat a PHP runtime as an ordinary website/tool app.

Exact Helper Commands

Use scripts for their named job instead of manually recreating their behavior. Review each diff after a mutating helper; patch helpers normalize structure but cannot prove application semantics.

Completion Gates

• Confirm authoritative repository, Docker documentation, Compose/image evidence, license, and topology; record unsupported facts instead of inventing them, and stop when the selected preflight route says to stop.
• Preserve the selected upstream service graph, dependencies, internal networks, persistence, and security controls. Give every Compose service labels.createdBy: "Apps" and a unique container_name based on ${CONTAINER_NAME} unless current 1Panel runtime evidence requires another shape.
• Build an authoritative control inventory from the selected official launch command, Compose, image, and entrypoint before editing. Record services, image commands and users, environment variables and fixed values, healthchecks, dependencies, ports, networks, mounts and mount options, capabilities, security options, privileged mode, devices, and host namespaces. Compare the final Compose against that inventory, preserve every source-backed control, and justify every omission or change with official source or target-platform evidence. A fixed upstream hardening value is not an optional install-form setting; keep it fixed unless evidence supports changing it.
• Build a capability contract for each official deployment shape. Record its user-visible capabilities and the exact service, image, environment, and dependency combination that enables each one. Preserve the full upstream capability set by selecting either the full upstream default or an officially/target-platform-proven capability-equivalent alternative. Select a reduced-capability profile only when the user explicitly requests it; disclosure does not substitute for capability preservation. For an authorized reduced profile, prove the remaining combination is supported, list the exact unavailable features in the README and report, and use any required compatible image variant; do not call it the default or source-equivalent topology. Missing compatibility evidence blocks scaffolding.
• Before assigning any route, write a deployment-shape census. Start from official install guides and their indexes or README, then enumerate every referenced sample or Compose root in the application and companion deployment repositories. For each discovered root, trace its include/template chain and record whether it is selected or rejected and why. A route conclusion that considers only the most obvious sample is incomplete.
• After the census, evaluate each deployment shape independently in a deployment-shape decision ledger. For each shape, record its exact root and release, support scope, default capability set, external dependency ownership, persistence boundary, migration and upgrade boundary, and disposition as selected, conditional, or rejected with evidence. Treat a documented operator-managed dependency as an external-service boundary, not a missing service. A more complex production topology does not invalidate a smaller official topology, and a production-ready label is scoped evidence, not an exclusivity claim. Invalidate a smaller shape only with exact-version evidence in one of these categories: officially required, exclusive, deprecated, or capability-incomplete. Assign platform_stack_terminal only after every capability-complete official shape has been evaluated and none can enter ordinary_candidate or specialized_conditional with satisfiable named prerequisites.
• The default capability set excludes optional features that are not enabled by default. Do not pre-publish optional listeners, mounts, devices, capabilities, or host permissions. Keep one only when the selected profile explicitly enables and fully configures it and the capability is validated; "for later configuration" is not evidence that it belongs in the selected profile.
• Apply the historical official source fallback before stopping for missing deployment evidence. A single 404 or moved page is not a terminal condition: inspect the exact release tree, version history, official documentation repositories, pinned historical Compose, and official image/startup sources, then record every attempted official source. When deployment evidence comes from a companion repository, pin its exact commit and trace the selected root through its actual include/template chain; an alternative file on a moving default branch is not evidence that the selected topology uses it. Stop only after those paths are exhausted and a concrete unsafe unknown remains; name the missing contract fact and the unsafe guessed decision it blocks.
• A terminal route does not waive OCI inspection. Inspect the OCI manifest and OCI config for each published image used by every viable official shape, including base, bootstrap, or runtime images named by launchers. If no immutable published registry artifact exists or registry access remains unavailable after the approved checks, record the unavailable registry fact and limit negative security or runtime claims; do not infer image controls from YAML alone.
• Build a startup configuration contract by inspecting every available exact-version authority among the official install examples, configuration reference, image defaults, entrypoint, and startup source; record unavailable authorities instead of requiring all of them to exist. Do not treat the selected official Compose as an exhaustive startup configuration list. Scope the ledger to required, startup-fatal, stability-bearing, or coupled inputs for the selected topology, plus any selected or default-dependent optional inputs. Record each value's default, empty-value rule, consumer, validation rule, secret format, stability requirement, and cross-field constraints, and prove the consumer and startup behavior from source or exact-image/runtime evidence. Reconcile every required value into the final Compose, data.yml, .env.sample, or source-backed lifecycle logic, then trace it to the application consumer. Whenever a form envKey, label, or type changes, re-review its default, rule, and values; keep every non-empty, non-secret, Compose-consumed form default consistent with .env.sample as defined in references/lifecycle-safety.md. Treat validated form values as literal data during template generation, never as regular-expression or replacement-program input. required: true or a generic paramComplexity rule does not prove the application-specific validation contract; enforce the full rule before Compose starts or stop. A successful Compose render does not prove that the panel default passes application startup validation; an unresolved or omitted required value blocks a pass claim.
• Record source-evidence.json.images[] for every selected version's Compose service image, including database, cache, browser, migration, and helper services. Bind the version, exact service, resolved image reference, and matching registry digest; prefer a digest-pinned runtime reference, but do not claim that a tag-only reference is immutable. The legacy single imageEvidence covers only a one-image Compose. For a multi-platform image, record the index digest separately from each platform child digest. Associate a platform child digest only from that same registry descriptor; do not infer it from descriptor order, the current host architecture, or a separate query. Recheck every declared platform-to-digest mapping before reporting it.
• For every service with a writable bind, add runtimeIdentity to its selected images[] entry (or legacy imageEvidence) with numeric startupUid, startupGid, steadyStateUid, steadyStateGid, an exact-version HTTPS source, and writableBindOwner. Use host-init only with generated --dir-owner/--fixed-dir-owner coverage for every bind, image-managed only with a separate HTTPS ownerEvidence, and root-runtime only when steadyStateUid is 0. Delivery validation rejects missing identity evidence or an unmatched non-root owner plan.
• Keep a minimal install form: expose only settings users need for the selected default topology. Do not mirror every optional upstream profile or environment variable; remove disabled profiles or resolve reviewed package defaults while maintaining Compose/form/.env.sample closure.
• For callback, origin, and externally visible base URLs, use the exact current upstream variable and expose one full public URL when user input is required. Do not reconstruct it from host, protocol, or port fields unless version-matched official evidence proves that contract equivalent. Keep the external URL separate from the internal listener: for a reverse proxy, preserve the documented internal scheme/port, TLS termination boundary, and trusted-proxy or hop settings. Do not set an internal listener to HTTPS without the application's required certificates and source-backed configuration.
• Treat .env as untrusted data in lifecycle scripts. Never source or eval it; parse only exact known keys, strip quotes, validate values, and resolve relative paths from the app root.
• Complete the references/lifecycle-safety.md path and mount ledger, including each source-backed mount mechanism, mount options, and operator-access contract. Treat source, target, read/write mode, propagation, and security options in authoritative Compose as required delivery defaults; preserve them exactly unless target-platform evidence proves incompatibility and a reviewed replacement preserves the same contract. A named volume is not a drop-in replacement for a configuration bind used by official host-side editing, backup, restore, or support procedures; preserve that fixed package-local bind and do not add an APP_DATA_DIR form unless a selectable host path is actually required. Derive startup and steady-state runtime UID/GID separately from the published OCI configuration, Compose user, and verified entrypoint/process behavior; keep mutable host paths package-local and confined before creation, permission changes, or cleanup. When the selected authoritative deployment uses a named volume for a non-root writable path, preserve that volume. When it uses a bind, use the explicit --dir-owner/--fixed-dir-owner helper with a source-backed identity on a direct child of the trusted version root, then verify the exact owner, mode, and a write probe as that identity. Change the mechanism only through the same target-platform incompatibility and equivalent-replacement gate. A plain root-created 0755 bind directory blocks delivery. Do not recursively change ownership on an unconfined or symlinked path.
• Report an observed owner or mode as an observation tied to the invoking UID/GID and umask. Claim a portable guarantee only when the delivered lifecycle script explicitly enforces that owner or mode and the exact-artifact test verifies it.
• Create or validate the exact source file for every file bind before Compose starts. Prove each generated secret format against the application contract, keep stable secrets across upgrade, URL-encode URL credentials, and apply the official escaping rules to every other connection-string grammar.
• Replace placeholders with real product metadata and meaningful translations in all required locales. English fields must contain English. Record the application and asset licenses; when exact redistribution terms require attribution, copyright or license text, source disclosure, or NOTICE delivery, include that required material in the package instead of relying on a link. When a license has material use restrictions, name and link it in the README instead of keeping it only in machine-readable evidence. Verify an asset's redistribution basis separately from the application code license; for an unresolved asset license or trademark permission, use the neutral placeholder immediately rather than shipping the asset with a future-confirmation note.
• Render and validate the exact delivered artifact without creating then removing a file it needs. Keep only lifecycle hooks that perform required work, and retain executable mode for every delivered hook. Missing no-op hooks are valid; preserve any source-backed setup, upgrade, or cleanup operation. Run baseline validation first, then bash scripts/validate-v2.sh --dir <app-dir> [--version <version>] --strict-store --i18n-mode strict --source-evidence-mode required --require-delivery-evidence; unresolved failures block a pass claim.
• Before finalizing the README or report, build a configuration claim ledger and compare each statement with the exact Compose, data.yml, .env.sample, and lifecycle scripts. Classify every described value as fixed, defaulted, generated, optional, or user-configurable. If an editable form field controls it, describe it as user-configurable with that default rather than fixed; contradictions block a delivery-ready claim.
• For every form field, record its install-time and steady-state consumer before choosing edit. A value generated once, written into persistent configuration, or identity-bearing must use edit: false unless an idempotent reconciliation or migration applies later edits to the real persisted consumer. Do not expose a control that only changes .env while the application continues using an older persisted value.
• Test in a real 1Panel development/test instance: clean install, application-specific readiness, restart, upgrade when applicable, uninstall, and task-owned cleanup. Report artifact paths, evidence, checks, risk-bearing permissions, assumptions, warnings, and every unexecuted runtime gate; static validation or HTTP 200 alone is insufficient. Distinguish files in the delivered AppStore package from run-only evidence caches. Do not claim that a run-only cache path is present in the delivered package.

Rule Priority

Judge every rule in this order:

1. Runtime and source-code hard rules from 1Panel-dev/1Panel
2. Official 1Panel wiki and official docs
3. Official appstore repository conventions
4. External references and practical articles

Only rules backed by runtime behavior or explicit official documentation should block generation or validation. Repository conventions are guidance unless validator mode explicitly upgrades them.

Source Policy (Evidence First)

Before adapting a new candidate, read references/source-policy.md, references/topology-preflight.md, and references/lifecycle-safety.md. Complete the topology decision before scaffolding or deployment testing: ordinary candidates may proceed, specialized conditional candidates need their recorded prerequisites satisfied, and platform-stack terminal candidates stop unless the user opens a separately scoped project.

Collect evidence according to source priority:

• User-provided official repository/documentation > official image docs > official appstore structure facts > third-party examples
• Without official Docker evidence, stop expanding; do not guess images, ports, volumes, UID/GID, or dependency injection methods
• When using third-party images, user must explicitly accept, and record source and risk in delivery notes
• Preserve high-risk runtime permissions when official compose, documentation, or source evidence shows that a core application feature requires them. This includes Docker or Podman Socket mounts, privileged: true, cap_add, host networking, host PID/IPC namespaces, device mappings, and relaxed security_opt settings. Do not remove a required permission merely to reduce scanner findings.
• Keep required high-risk access no broader than upstream needs, test the feature that depends on it, and document the exact permission, feature dependency, and host impact in the app README and delivery notes. A risk label is required; deletion is not the default remediation.

For existing app updates, version additions, image lineage changes, dependency changes, volume/env rewrites, or lifecycle script edits, also read references/upgrade-maintenance.md before changing files. Treat upgrade safety as part of the adaptation contract, not a post-submit note.

For PHP runtime work, especially when converting a historical package such as php-unofficial into a real 1Panel PHP runtime, also read references/php-runtime.md. PHP runtimes are not packaged like ordinary website/tool apps, and the runtime picker behavior is source-backed rather than guessable from generic appstore patterns.

Recommended Directory Structure (Store-Aligned)

Field Hierarchy Constraints (Aligned with Official apps/ Facts)

Note: In the official repository (1Panel-dev/appstore dev branch), the data.yml field hierarchy under v2 structure is very stable; this skill's validate-v2.sh --strict-store performs strict validation according to this.

• Language codes: Application metadata uses runtime keys zh-hant, pt-br, and es-es. UI locale names such as zh-Hant are accepted as historical input aliases, then normalized for generated output. See the pinned source evidence in references/1panel-sources.md.

Application-level: apps/<app>/data.yml

• Top-level only allows: name / tags / title / description / additionalProperties
• Top-level type appearing: WARN only (historical/non-standard field; official regular write doesn't place at top level)
• architectures: Must be in additionalProperties.architectures (100% present in official samples)

strict-store additionalProperties required (missing = FAIL):

• key / name / tags / type / website / document / architectures
• github / shortDescZh / shortDescEn / crossVersionUpdate / limit
• (Others like recommend / description / memoryRequired can maintain WARN by occurrence rate)

Version-level: apps/<app>/<ver|latest|stable>/data.yml

• Top-level only allows: additionalProperties
  • Can be null or object (but under strict-store, recommend object with required fields filled)
• formFields must be in additionalProperties.formFields (top-level formFields not allowed)
• Prohibit architectures: Version-level data.yml (same level as docker-compose.yml) should not have architectures (neither top-level nor inside additionalProperties)

Convention supplement (this skill's default artifact style):

• root data.yml top-level description uses single-line string (not map).
• root data.yml additionalProperties.shortDesc uses shortDescZh/shortDescEn (not map).
• additionalProperties.description uses i18n map, complete all 12 supported languages for delivery: en/zh/zh-hant/ja/ko/ru/ms/pt-br/tr/es-es/fa/lo.
• root data.yml uses hierarchical structure: top-level tags and additionalProperties.tags both exist and are semantically consistent (allow redundant expression).
• Descriptive summaries: title may be the product name. Top-level description and additionalProperties.shortDescZh/shortDescEn must explain the application's purpose in a short sentence; a product name alone fails strict-store validation. Keep their meaning consistent with the multilingual description. patch_root_data_yml.py and appstore_i18n.py --normalize can repair missing/name-only summaries from supplied Chinese and English descriptions while preserving valid prose.
• Translation constraint (strong constraint): additionalProperties.description must be the multilingual translation of the above shortDescZh (not repetition of project name/title).
• architectures (only root data.yml) represents Docker image supported architecture list; should be in additionalProperties.architectures, using hierarchical array (e.g., - amd64 / - arm64); if cannot reliably obtain (e.g., no manifest info/offline), default only fill - amd64.

formFields Structure Facts (version-level)

Location: additionalProperties.formFields: [ ... ]

formFields[] item common fields

• envKey (required)
• type (required)
• required (required)
• default (common)
• rule (optional; common set below)
• labelZh / labelEn (high-frequency; recommend providing both)
• label (multi-language map, high-frequency)
• child (appears when type: apps)

formFields[].type allowed set (based on official dev/apps real samples)

• number
• password
• select
• text
• apps
• service

Notes:

• Official repo has both patterns:
  • type: apps + child.type: service
  • Direct type: service
• Therefore validator should allow service in formFields[].type, but adapted artifacts can prefer apps + child.service to express "dependency selection → service instance selection" two-step semantics.

rule common set (for this skill validation)

• paramPort (most common, for PANEL_APP_PORT_*)
• paramExtUrl
• paramCommon
• paramComplexity

Treat this as an allowed set, not a requirement to populate rule. Normally only externally published port fields use rule: paramPort; omit rule from secrets, URLs, selectors, domains, and ordinary text unless a demonstrated 1Panel parser or application-format requirement needs it.

formFields[].edit (consumer-backed editability)

Based on official v2 app library docker-compose.yml and same-directory version-level data.yml actual write:

• edit is bool in DTO (default equivalent to false), but official library explicitly writes edit: true for many fields.
• Choose edit from the value lifecycle, not from a blanket editable default:
  • Use edit: true only when the steady-state consumer reads the changed value directly, or an idempotent reconciliation or migration safely applies it to persisted state.
  • Use edit: false for a value generated once, identity-bearing configuration, panel injection, or any value whose persisted consumer is intentionally not regenerated. Typical injection keys include PANEL_DB_*, PANEL_REDIS_*, and PANEL_MINIO_*.
  • Dependency selection fields (type: apps/service) may use edit: true only when the linked-resource lifecycle supports changing the selection; enumeration alone is not migration evidence.
• Validation strategy: validate-v2.sh --strict-store will WARN when a required non-selector field lacks an explicit edit decision (not FAIL, to avoid rejecting official historical output). Resolve the warning from the consumer lifecycle; do not silence it mechanically with edit: true.

Database / Redis Dependency Injection (Panel Fixed envKey)

Before preserving an upstream-bundled database/cache sidecar, inspect the target appstore and a current 1Panel store for reusable runtime applications and service registration. When a compatible 1Panel-managed runtime exists and the application supports an external service, prefer the panel runtime selector path and panel fixed envKeys; do not wait for a later review reminder to replace the bundled dependency.

Dependency preference order:

1. A compatible, selectable 1Panel-managed runtime exposed through /apps/services/<key> and the corresponding resource records.
2. A documented external service configuration when no reusable panel runtime is available.
3. The upstream-bundled database/cache sidecar only when the runtime selector path is unavailable, unregistered, incompatible, or the upstream application requires the bundled topology.

For applications supporting multiple database engines, keep one app key and expose the engines that have independent panel/runtime evidence through one type: apps plus child.type: service selector. Map engine-specific ports through selector params. Do not create database-specific app keys or version directories merely to represent engine choice, and do not advertise an engine that only passes static compose validation.

Common fixed envKeys (recommend using as needed):

• Database: PANEL_DB_TYPE, PANEL_DB_HOST, PANEL_DB_NAME, PANEL_DB_USER, PANEL_DB_USER_PASSWORD
• Redis: REDIS_HOST, REDIS_PORT, PANEL_REDIS_ROOT_PASSWORD, REDIS_DB

If users are expected to choose a reusable 1Panel-managed dependency from the install UI, do not leave the dependency host field as plain type: text.

• For database-family selectors, prefer type: apps plus child.type: service.
• For single-step selectors such as Redis service reuse, prefer type: service with the dependency key (for example key: redis) on the host envKey field.
• A package that only accepts manual host input is not equivalent to a package whose UI can actually select a store/local dependency app.

Scaffold supports optional injection template:

• When running scripts/scaffold-v2.sh, add --with-panel-deps (or alias --with-panel-db-redis), will automatically add above DB/Redis related formFields in generated <version>/data.yml (including labelEn/labelZh + a label map using runtime locale keys).

Key points for adaptation:

• Treat store-runtime discovery as an adaptation preflight step: search existing app definitions for the dependency key, query the panel store metadata, and verify that an installed instance appears in /apps/services/<key> before deciding the final service topology.
• Treat the selector value as a 1Panel app key, not a display-label alias. mysql and localmysql are distinct values and must be verified independently through /apps/services/mysql and /apps/services/localmysql; do not advertise one because the other works.
• version/data.yml uses type: apps + child.type: service to inject PANEL_DB_HOST (reference 1Panel store app common dependency injection pattern).
• Keep service enumeration separate from database lifecycle integration. A running option returned by /apps/services/<key> proves the selector can enumerate that instance, but not that 1Panel created or linked an application database. When the form also requests PANEL_DB_NAME, PANEL_DB_USER, and PANEL_DB_USER_PASSWORD, require install and upgrade evidence that the host envKey is present in the services payload and the installed app reports linkDB: true or the expected resourceKeys; then verify schema/user creation and cleanup behavior separately.
• For packages that require a runtime administrator password to initialize several upstream-defined schemas, use the actual password of the selected installed runtime. A form default is only a template and must not be treated as the current runtime credential. Do not change a shared runtime's authentication mode to make a smoke test pass.
• App uninstall does not universally own external database data. Confirm whether selector-created linked resources are removed by 1Panel, and explicitly clean only task-owned schemas/users during tests. Preserve manually managed external databases unless the user separately authorizes their removal.
• When converting an existing package from manual host input to a selector-backed dependency, keep the effective runtime envKey stable when possible. For example, changing REDIS_HOST from type: text to type: service is usually upgrade-safe because existing .env values still map to the same compose/app variable.
• If the selector conversion requires a renamed envKey or adds a new selector-driving field such as PANEL_DB_TYPE, treat that as an upgrade migration item and backfill it in scripts/upgrade.sh when possible.
• PostgreSQL-only rule: if the app relies on panel-side PostgreSQL provisioning (CreateDatabase in install task logs), runtime validation should use a real 1Panel-installed PostgreSQL app in the same panel. Pointing the service field at an arbitrary external hostname can bypass the intended provisioning path and create misleading failures.
• For that PostgreSQL-only path, keep the application PostgreSQL user (PANEL_DB_USER) distinct from the PostgreSQL service admin/root account. Reusing the admin username can make a correct package fail during install with User already exists.
• Do not automatically generalize those PostgreSQL-specific behaviors to MySQL; verify MySQL-linked adaptations from their own 1Panel task/runtime evidence before carrying the rule over.
• For format-sensitive secrets, do not assume a generic random password is a valid application value. Examples: Laravel APP_KEY expects Laravel-compatible key material, while Mastodon ACTIVE_RECORD_*, SECRET_KEY_BASE, OTP_SECRET, and VAPID_* have upstream-specific generator commands and formats.
• When official docs expose a generator helper, prefer scripts/init.sh / scripts/upgrade.sh to generate or normalize those values from the official image/helper command instead of shipping a fixed sample secret in data.yml or trusting a generic panel-generated random string.
• If scripts/init.sh or scripts/upgrade.sh replaces a panel-provided secret with a normalized/generated value, persist that final value under the app's configurable data path and restore it during later upgrades. Real 1Panel upgrades can replay the original install form value instead of the mutated .env, which can break apps that silently rotate APP_KEY, DB_PASSWORD, or similar persisted secrets.
• Keep that secret-persistence rule distinct from the PostgreSQL-only provisioning notes above: the replay problem can affect MySQL-, PostgreSQL-, or non-DB secret fields, even though the dependency-provisioning behavior is not shared across engines.
• When simplifying forms, retain documented security controls such as user registration, anonymous access, and administrator exposure, or provide verified configuration instructions with the effective default. Review the before/after behavior so removing a switch does not silently inherit a more permissive upstream default.
• If the compose uses network_mode: host, its listener occupies the host port directly even without a ports: block. Keep the install-form envKey as PANEL_APP_PORT_* so 1Panel performs its port-occupation check, map the upstream listener variable from that key (for example, NETDATA_LISTENER_PORT=${PANEL_APP_PORT_HTTP}), and verify the application consumes it. A disabled/fixed port field must still match the real built-in listener instead of being treated as a free-to-randomize published port.
• For host-network adaptations tested from a containerized smoke runner, runtime probing may need the Docker host gateway (or another host-reachable address) rather than 127.0.0.1 inside the panel container.
• docker-compose.yml if application uses DATABASE_* variables, need to map in compose:
  • DATABASE_HOST: ${PANEL_DB_HOST}
  • DATABASE_USER: ${PANEL_DB_USER}
  • DATABASE_PASSWORD: ${PANEL_DB_USER_PASSWORD}
  • DATABASE_DBNAME: ${PANEL_DB_NAME}
• Redis password similarly: REDIS_PASSWORD: ${PANEL_REDIS_ROOT_PASSWORD} (if application field name differs, map as needed).
• Validation must prove the selector path, not only connectivity. A smoke/install report should show the d

…(truncated)