# Docker To Sealos

> Convert Docker Compose files or installation docs into production-grade Sealos templates with role-specific personal low-load resource sizing, official route and runtime semantics, KubeBlocks database and Job gates, and managed or optional S3 storage contracts. Use when user has a docker-compose.yml and wants a Sealos or Kubernetes template, wants to migrate from Docker Compose to Sealos, needs to convert container orchestration configs to Sealos format, or mentions compose-to-template conversion. Also triggers on "/docker-to-sealos".

- Skill: `labring/docker-to-sealos` (Agent Skill, multi-file: 37 files)
- Install (CLI): `npx skillmds@latest add labring/docker-to-sealos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/labring/docker-to-sealos/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: labring (https://skillmd.com/u/labring)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/labring/docker-to-sealos

---


# Docker to Sealos Template Converter

## Identity and Discovery

- **Owner:** `docker-to-sealos` (`/docker-to-sealos` and Compose, install-doc, or Sealos template conversion requests).
- **Class:** `local-artifact-mutation` with a validated template handoff to `sealos-deploy`.
- **Canaries:** `DTS-RULE-PRECEDENCE`, `DTS-MUST-MAP`, and `DTS-QUALITY-GATE`.

## Scope and Boundaries

Accept Docker Compose, installation documentation, or an existing template update request and write the named template artifact under `template/<app>/index.yaml` plus owned validator evidence. Do not perform a live cloud mutation. Keep rule provenance, database topology, resource order, declared inputs, and secret boundaries inside this skill. A template is a handoff candidate only after all required gates pass.

## Risk and Confirmation

The governance order remains entry MUST rules, Sealos specs/database templates, then mappings/examples. `references/must-rules-map.yaml` and `references/rules-registry.yaml` are coupled load-bearing sources. Public exposure, destructive changes, credential changes, and system-tool installation retain explicit confirmation; generated values and connection data remain redacted.

## Lifecycle Workflow

For each request, analyze input, infer metadata, plan resources, apply conversion rules, validate the final artifact, and hand off only after the complete quality gate passes. Emit request-scoped `success`, `stopped`, or `error`; each result carries source provenance, artifact paths, validator evidence, and redaction status. The existing analysis → inference → resource planning → conversion workflow remains the domain extension below.

## Progressive Disclosure

Load the relevant owned reference family one level deep after the core canaries are visible. Preserve the MUST-map and rules-registry coupling, rule precedence, and existing validator scripts; do not replace them with a generic converter or `railpack build` path.

## Output, Stop, and Error States

- `success`: source/provenance, final Template YAML, conversion summary, declared inputs, topology/storage/database evidence, consistency/MUST-map/registry/quality-gate evidence, and redaction result.
- `stopped`: missing input, unresolved source, or confirmation boundary with observed evidence, redaction result, and safe next action; do not hand off an unvalidated artifact.
- `error`: failed rule, registry, topology, artifact, or quality gate with named source/artifact, sanitized diagnostic, redaction result, and recovery action.

## Handoffs

Send the complete typed handoff below for direct conversion. Deploy re-checks its own auth, scope, and Runtime Truth gates.

```yaml
target: sealos-deploy
inputArtifact: final Template YAML plus consistency, MUST-map, registry, topology, and quality-gate evidence
allowedAction: deploy after required inputs and all downstream gates pass
failureReturn: failed rule, registry, topology, artifact, or quality-gate diagnostics
responseOwner: docker-to-sealos
```

## Verification

Run consistency, MUST coverage, and `quality_gate.py` against the exact final template. Use baseline cases `docker-to-sealos-positive-quality-gate` and `docker-to-sealos-violating-missing-rule`; missing registry/MUST evidence blocks deployment.

## Overview

Convert Docker Compose files or installation docs into production-grade Sealos templates.
Execute analysis, conversion, validation, and output automatically when the required
inputs and confirmations exist; stop with a safe next action when a required input
or gated operation is unresolved.

## Governance and Rule Priority

Use the following precedence to prevent rule drift:

1. `SKILL.md` MUST rules (this file)
2. `references/sealos-specs.md` and `references/database-templates.md`
3. `references/conversion-mappings.md` and `references/example-guide.md`

If lower-priority references conflict with higher-priority MUST rules, update the lower-priority files.
Do not keep conflicting examples.

### Source Precedence and Branch Boundary

Use this source precedence for every conversion and record the selected source in
the conversion report:

1. Existing template topology and explicit user intent for an update.
2. Entry MUST rules and the coupled `must-rules-map.yaml` / `rules-registry.yaml`.
3. Official Kubernetes installation/runtime documentation.
4. Compose or install documentation selected for the request.
5. Repository config, README, Dockerfile, and lockfile evidence.
6. Normalized `analysis.json.build_environment` evidence when the prepare-only
   branch supplies it.

Raw Railpack JSON is not a conversion source. On `brain-deploy-preview`, retain
explicit config/README/Dockerfile/lockfile precedence, consume normalized build
environment evidence, and keep the Dockerfile plus sandbox Kaniko path. The
preview flow does not replace this path with `railpack build`, BuildKit, or live
deployment behavior.

## Conversion Payload

Keep this payload request-scoped and repository-relative so deploy can reuse the
discovery result:

```yaml
source:
  kind: compose | install-doc | existing-template
  paths: selected source files
  precedence: ordered source list
inference:
  app: metadata and runtime bundle evidence
  topology: resource roles, feature conditions, and replica counts
resources:
  ordered: Template CR, storage, database, workloads, App resource
  database: KubeBlocks evidence when applicable
  storage: PVC or managed object-storage evidence
  secrets: declared inputs with redaction status
artifact:
  template: template/<app>/index.yaml
  topology_evidence: .sealos/topology-evidence/<app>.yaml when required
verification:
  consistency: pass | fail
  must_map: pass | fail
  registry: pass | fail
  quality_gate: pass | fail
terminal_state: success | stopped | error
safe_next_action: request-scoped recovery or handoff action
```

The payload and final artifacts contain no passwords, tokens, kubeconfig contents,
environment values, complete connection strings, or validator-only secrets.

## Workflow

### Step 1: Analyze input

Extract from Docker Compose/docs:

- application services vs database services
- volumes/config mounts/object storage requirements
- ports, dependencies, service communication
- env vars and secret usage
- startup-time validation rules for bootstrap credentials, API keys, salts, secrets, and feature flags
- account bootstrap mode from the exact selected release: functional first-user signup, mandatory bootstrap credentials, or optional root reconciliation/bootstrap
- multi-service web roles: browser entry, REST API, OpenAI/API gateway, docs, workers, and one-shot jobs
- resource limits/requests and health checks
- if official Kubernetes installation docs/manifests are available, also extract app-runtime behavior from them (bootstrap admin fields, external endpoint/protocol assumptions, health probes, startup/init flow, migration ordering)
- if official compose/docs provide multiple cooperating services, record the official runtime bundle source, component list, image versions, public entry routes, and critical env vars
- record the selected source topology: topology-bearing resource roles, feature conditions, and application or database component replica counts

### Step 2: Infer metadata

Infer and normalize:

- app name, title, description, categories
- official URL, gitRepo, icon source (prefer square/circular icon-first assets such as app icons, favicons, or avatars; avoid rectangular wordmark/text logos)
- locale/i18n metadata

### Step 3: Plan resources in strict order

Generate resources in this order:

1. Template CR
2. ObjectStorageBucket (if needed)
3. Database resources (ServiceAccount → Role → RoleBinding → Cluster → Job if needed)
4. App workload resources (ConfigMap/Secret → Deployment/StatefulSet → Service → Ingress)
5. App resource (last)

### Step 4: Apply conversion rules

Apply field-level mappings from `references/conversion-mappings.md`, including:

- image pinning and annotation mapping
- port/service/ingress conversion
- env var conversion and dependency ordering
- storage conversion and vn naming (`scripts/path_converter.py`)
- service-name to Kubernetes FQDN conversion
- for DB URL/DSN envs (for example `*_DATABASE_URL`, `*_DB_URL`), when Kubeblocks `endpoint` is host:port, inject `host`/`port`/`username`/`password` via approved `secretKeyRef` envs and compose the final URL with `$(VAR)` expansion
- edge gateway normalization: when Compose includes Traefik-like edge proxy plus business services, skip the proxy workload and expose business services via Sealos Ingress directly
- TLS offload normalization for Sealos Ingress: when a business service exposes both 80 and 443, drop 443 from workload/service ports and remove in-container TLS certificate mounts (for example `/etc/nginx/ssl`, `/etc/ssl`, `/certs`) unless official Kubernetes docs explicitly require HTTPS backend-to-service traffic
- multi-service web normalization: expose the verified browser entry in the App resource, expose API/gateway/docs only when they are intended public surfaces, and keep workers private with no Service/Ingress
- URL topology: browser-facing env vars must use public HTTPS URLs, while server-to-server env vars must use Kubernetes Service FQDNs unless the app explicitly requires public callbacks
- WebSocket ingress normalization: when the public entry is `ws://`, `wss://`, CDP/Chrome DevTools, a game socket, or a WebSocket-named port/service, expose it with WebSocket nginx ingress annotations
- StatefulSet service identity: for a single-component app with no documented headless or stable per-Pod DNS requirement, use the public application Service as `spec.serviceName` and keep the workload, Service, root Ingress, and manager identity aligned; preserve documented HA/headless governing Services and expose them through a separate public application Service
- prefer `scripts/compose_to_template.py --kompose-mode always` as deterministic conversion entrypoint (require `kompose` for reproducible workload shaping)
- for existing-template updates, keep the current template's topology-bearing resources, feature conditions, and replica counts as the baseline
- for new conversions, keep the selected Compose services and `deploy.replicas` values as the topology baseline
- use official Kubernetes installation docs/manifests to align app-runtime semantics such as bootstrap fields, endpoints, probes, and startup ordering
- keep optional or recommended workers, caches, and HA replicas outside the emitted topology unless the selected source topology or explicit user intent includes them
- keep every feature input scoped to its documented capability; database and object-storage inputs must not add unrelated workloads, caches, or replicas
- when official compose/docs define a multi-component runtime bundle, keep runtime-required components, entry routes, critical env vars, and component image versions aligned to one official release/compose source
- before converting a host directory mount to persistent storage, verify whether the image already ships required files at that target path; avoid hiding image-bundled manifests, dependency lists, or config defaults behind a fresh empty PVC

### Step 5: Apply database strategy

- Database services must be generated as KubeBlocks `Cluster` resources. Do not convert PostgreSQL/MySQL/MongoDB/Redis/Kafka Compose database services into raw Kubernetes `Deployment` or `StatefulSet` workloads.
- PostgreSQL must follow the pinned version and structure requirements.
- MySQL/MongoDB/Redis/Kafka must use templates and secret naming from `references/database-templates.md`.
- Add DB init Job/initContainer when application database bootstrap requires it.
- For PostgreSQL custom databases (non-`postgres`), the init Job must wait for PostgreSQL readiness before execution and create the target database idempotently.
- Database client images may be used in app `initContainers` and init/migration/bootstrap Jobs for readiness and bootstrap gates.
- Critical application compatibility objects must be verified in live database state. Use idempotent initContainer self-healing for compatibility views, legacy tables/views, indexes, extensions, search paths, and bootstrap state that the app requires on every cold start.
- One-shot init Jobs may create initial databases or seed state, but app startup gates must verify the final database objects directly. Treat TTL-expired Jobs as historical evidence and rely on database state for acceptance.
- Worker, gateway, and background services that depend on app migrations must wait for the required tables, migration markers, or app-specific readiness objects, not only for the database port.
- Redis readiness probes or initContainers must tolerate authenticated Redis responses such as `NOAUTH` or `Authentication required` when credentials are not needed for readiness.
- PostgreSQL bootstrap shell must use safe quoting patterns. Prefer shell-level existence checks plus simple SQL statements when possible. Use single-quoted heredocs or SQL files for psql variable interpolation, and avoid PL/pgSQL `DO $$` blocks in inline shell commands when a guard query can express the same logic.
- Do not use `psql -c "..."` for `:'var'` variable interpolation. Use `psql -v name=value <<'SQL' ... :'name' ... SQL` or pass already-safe literal SQL.

### Step 6: Generate output files

Always produce:

- `template/<app-name>/index.yaml`
- `template/<app-name>/logo.<ext>` when official icon is resolvable, prioritizing square/circular icon-first artwork and avoiding rectangular wordmark/text logos

Never create:

- `template/<app-name>/README.md`
- `template/<app-name>/README_zh.md`

README authoring is out of scope for this skill. If the Template CR requires README URLs, populate URL fields in `index.yaml` only and leave file creation to a dedicated README skill.

### Step 7: Validate before output

Run validator and self-tests before delivering template output.
If validation fails, fix template/rules/examples first.
For web applications, live validation must include runtime log hygiene: inspect init and main container logs after first readiness, after login or setup, and after one documented API negative route or unique missing-static-asset request. SPA client routes may return the HTML shell with HTTP 200; recurring traceback-style warnings remain template failures even when Pods are Ready.
For login-gated web applications, live validation must prove the real credential/session flow with one authenticated API or page before resource tuning or cleanup.
For managed or private object storage, live validation must upload known bytes through the authenticated application flow, read or download the object, compare its SHA-256 digest, confirm delivery through the application proxy or a time-bounded presigned URL, and verify the raw anonymous object request remains restricted. Optional object storage must validate the local-storage and managed-bucket branches independently.

## MUST Rules (Condensed)

### Naming and metadata

- Template `metadata.name` must be hardcoded lowercase; do not use `${{ defaults.app_name }}`.
- Template CR folder name must match `metadata.name`.
- Template CR must include required metadata fields (`title`, `url`, `gitRepo`, `author`, `description`, `icon`, `templateType`, `locale`, `i18n`, `categories`).
- Template `spec.readme` must point to `https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README.md`.
- Template `spec.i18n.zh.readme` must point to `https://raw.githubusercontent.com/labring-actions/templates/kb-0.9/template/<app-name>/README_zh.md`.
- These README fields are URL references in `index.yaml` only; this skill must not create or update the referenced README files.
- `icon` URL must point to template repo raw path for this app on `kb-0.9` branch.
- `template/<app-name>/logo.<ext>` must use square/circular icon-first artwork (for example app icon/favicon/avatar), and must not use rectangular wordmark/text logos.
- `i18n.zh.description` must be written in Simplified Chinese.
- Omit `i18n.zh.title` when it is identical to `title`.
- `categories` must only use predefined values (`tool`, `ai`, `game`, `database`, `low-code`, `monitor`, `dev-ops`, `blog`, `storage`, `frontend`, `backend`).

### App resource

- App resource must use `spec.data.url`.
- App resource `spec.displayType` must be `normal`.
- App resource `spec.type` must be `link`.
- App resource `spec.data.url` must be the browser entry URL that succeeds from a fresh Sealos launch. For apps with safe-path, setup-path, or entrance-path behavior, verify the configured path and root path, then choose the URL that supports login or first-run setup without hidden prior navigation.
- SSR/Next.js/React server apps must not use a path that renders a server-side exception as the App URL or HTTP probe. Treat visible `Application error`, `server-side exception`, `Internal Server Error`, or `Unhandled Runtime Error` text as a failed entry path even if the HTTP status is 2xx/3xx.
- Never use `spec.template` in App resource.
- `cloud.sealos.io/app-deploy-manager` label value must equal resource `metadata.name`.
- `metadata.labels.app` label value must equal resource `metadata.name` for managed app workloads.
- The primary business container name must equal workload `metadata.name` for managed app workloads; sidecar/helper containers may use distinct descriptive names.
- Application `Service` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `spec.selector.app`.
- Runtime component-scoped `ConfigMap` resources must define `metadata.labels.app` and `metadata.labels.cloud.sealos.io/app-deploy-manager`, and both labels must match `metadata.name`; bootstrap-only ConfigMaps used only by init containers to copy initial config into persistent storage must not define either label.
- Application `Service` resources must use the same component name across `metadata.name`, `metadata.labels.app`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and `spec.selector.app`.
- Root-path `Ingress` resources (`pathType: Prefix`, `path: /`) must use the same component name across `metadata.name`, `metadata.labels.cloud.sealos.io/app-deploy-manager`, and backend `service.name`; non-root or non-Prefix Ingress rules may route to a different backend service.
- Root-path `Ingress` resources (`pathType: Prefix`, `path: /`) must use `backend.service.port.number`, and the number must match a declared `spec.ports[*].port` on the referenced application `Service`.
- Root-path Prefix routes must be the first entry in each HTTP `paths` list so Launchpad public-address discovery selects the application entry route.
- Service `spec.ports[*].name` must be explicitly set (required for multi-port services).
- HTTP Ingress must include required nginx annotations (`kubernetes.io/ingress.class`, `nginx.ingress.kubernetes.io/proxy-body-size`, `nginx.ingress.kubernetes.io/server-snippet`, `nginx.ingress.kubernetes.io/ssl-redirect`, `nginx.ingress.kubernetes.io/backend-protocol`, `nginx.ingress.kubernetes.io/client-body-buffer-size`, `nginx.ingress.kubernetes.io/proxy-buffer-size`, `nginx.ingress.kubernetes.io/proxy-send-timeout`, `nginx.ingress.kubernetes.io/proxy-read-timeout`, `nginx.ingress.kubernetes.io/configuration-snippet`) with expected defaults.
- WebSocket Ingress must include required nginx annotations (`kubernetes.io/ingress.class`, `nginx.ingress.kubernetes.io/proxy-body-size`, `nginx.ingress.kubernetes.io/proxy-read-timeout`, `nginx.ingress.kubernetes.io/proxy-send-timeout`, `nginx.ingress.kubernetes.io/backend-protocol`, `nginx.ingress.kubernetes.io/ssl-redirect`) with `backend-protocol: WS` and `3600` read/send timeouts.
- CronJob resources must define labels `cloud.sealos.io/cronjob`, `cronjob-launchpad-name`, and `cronjob-type`; `cloud.sealos.io/cronjob` must equal `metadata.name`, `cronjob-launchpad-name` must be `""`, and `cronjob-type` must be `image`.
- When official application health checks are available, managed workloads must define `livenessProbe`, `readinessProbe`, and (for slow bootstrap apps) `startupProbe`, aligned with official endpoints/commands.
- For public images that are verified to run as a non-root UID, managed app workloads and init Jobs should set restricted-compatible security context (`runAsNonRoot`, `runAsUser`, `runAsGroup`, `fsGroup`, `seccompProfile: RuntimeDefault`, `allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`) unless the image requires root or extra capabilities.

### Official Kubernetes alignment

- If official Kubernetes installation docs/manifests are available, conversion must reference them and align critical runtime settings before emitting template artifacts.
- When official Kubernetes docs/manifests and Compose differ, prefer official Kubernetes runtime semantics for app behavior (bootstrap admin fields, external endpoint/env/protocol, health probes), unless doing so violates higher-priority Sealos MUST/security constraints.
- For existing-template updates, preserve the current template's topology-bearing resource inventory, conditions, and replica counts; for new conversions, preserve the selected Compose topology and `deploy.replicas` values.
- Use official Kubernetes docs/manifests to align application runtime semantics; add optional or recommended workers, caches, and HA replicas only when the selected source topology or explicit user intent includes them.
- Each application feature input must gate only resources and settings for that documented feature; database and object-storage inputs must not change unrelated workload inventory or replica counts.
- Topology-sensitive validation must provide `.sealos/topology-evidence/<app-name>.yaml` as validator-only `TopologyEvidence`; final Sealos Template artifacts must stay free of topology validator metadata.
- When official compose/docs provide a multi-component runtime bundle, template artifacts must preserve runtime-required components, public entry routes, critical env vars, and image versions from the same official release/compose source.
- Templates using official multi-component runtime evidence must provide a separate `RuntimeBundleEvidence` YAML file during validation, while final Sealos Template artifacts stay free of runtime-bundle validator metadata.

### Images and pull policy

- Do not use `:latest`.
- Resolve versions with `crane`: prefer an explicit version tag (for example `v2.2.0`), and fallback to digest pin only when a deterministic version tag is unavailable.
- Avoid floating tags (for example `:v2`, `:2.1`, `:stable`); use an explicit version tag or digest.
- Managed workload image references must be concrete and must not contain Compose-style variable expressions (for example `${VAR}`, `${VAR:-default}`); resolve to explicit tag or digest before emitting template artifacts.
- Application `originImageName` must match container image.
- Known public-image managed app workloads must omit `template.spec.imagePullSecrets`; when a registry-authenticated workload needs a pull Secret, it may reference only the app-scoped Secret `${{ defaults.app_name }}`.
- The registry pull Secret is runtime-managed by `sealos-deploy` using local `gh` CLI credentials for private GHCR images; do not expose raw registry credential inputs in generated templates.
- All containers must explicitly set `imagePullPolicy: IfNotPresent`.

### Storage

- Do not use `emptyDir`.
- Use persistent storage patterns (`volumeClaimTemplates`) where storage is needed.
- StatefulSet resources with `volumeClaimTemplates` must keep standard workload labels such as `app` and `cloud.sealos.io/app-deploy-manager`, and omit only `cloud.sealos.io/deploy-on-sealos` from both StatefulSet `metadata.labels` and `volumeClaimTemplates[].metadata.labels`.
- `volumeClaimTemplates[].metadata` must include a path-derived `name`, `annotations.path`, and `annotations.value: '1'`, and each claim must match a container `volumeMount` with the same name and path.
- PVC request must be `<= 1Gi` unless source spec explicitly requires less.
- ConfigMap data keys must follow vn naming (`scripts/path_converter.py`), including `/`, `-`, `.`, and other special characters.
- ConfigMaps mounted by managed Deployment/StatefulSet workloads must use `metadata.name == workload.metadata.name`.
- ConfigMap workload volumes must use `<workload-name>-cm`, and every ConfigMap `data` key must be mounted as its own `volumeMount` with `subPath` exactly equal to that key.
- Omit ConfigMap volume `defaultMode` in managed templates. Invoke mounted scripts through `/bin/sh /path/script`; copy to persistent storage and apply `chmod` in an initContainer when an application truly requires an executable file.
- Avoid long inline startup scripts or heredocs in `command`/`args`; place initialization/start scripts in ConfigMap files and invoke them with a short command.
- Classify object storage from official application docs before generating inputs: required capability, application-level optional capability, or externally managed storage.
- If object storage/S3 integration is Enterprise, paid, commercial, subscription, or license-gated in the upstream application, keep the public template on the community-supported storage path (for example filesystem/PVC) and expose no standard `ObjectStorageBucket` or S3 input for that feature.
- When object storage is required and Sealos S3 compatibility satisfies the application contract, create unconditional `ObjectStorageBucket` resources for the documented bucket topology and inject Sealos object-storage secrets.
- A template with managed `ObjectStorageBucket` must use it as the sole object-store data plane and omit bundled MinIO server workloads, Services, Ingresses, PVCs, and local object-storage credentials.
- Resolve object-storage provider/backend selector inputs during conversion, and do not combine a managed `ObjectStorageBucket` with bundled `minio/minio`, `bitnami/minio`, or `bitnamilegacy/minio` server images.
- Use a compatibility proxy only when official protocol evidence requires request adaptation.
- An object-storage compatibility proxy must declare `metadata.annotations.docker-to-sealos.object-storage-compatibility-proxy-source` as a credential-free HTTPS source URL or `user-request:<reference>`, remain stateless, and omit persistent volumes.
- External S3/object-storage credential inputs require `metadata.annotations.docker-to-sealos.external-object-storage-source` as a credential-free HTTPS source URL or `user-request:<reference>`, and must not coexist with `ObjectStorageBucket`.
- Managed or private object-storage acceptance must prove authenticated application upload and read/download with matching content, application-proxy or time-bounded presigned delivery, and restricted raw anonymous access; optional object storage must pass both local-storage and managed-bucket branches.

The deploy handoff is withheld until consistency, MUST-map coverage, registry,
topology evidence, and `quality_gate.py` all pass against the exact final template.
Missing or stale evidence produces `error` and returns to the failed rule or
artifact owner.

### Env and secrets

- Non-database sensitive values/inputs use direct `env[].value`.
- When an official runtime profile constrains an env value's format or length, use a valid literal or a required input without a generated default; bare `${{ random(n) }}` is invalid for hex- or encoding-constrained values.
- Internal credentials that an official runtime library can deterministically derive from opaque entropy may use a quoted instance seed in `spec.defaults`; every consuming role must derive and validate the same final values, remove the seed before exec, and expose no user input for the derived values.
- Persisted runtime-secret contracts marked with `docker-to-sealos.runtime-secret-contract: persisted` must generate from durable runtime entropy, apply restrictive permissions with an atomic replacement, validate before `exec`, and keep the final secret out of diagnostics.
- When an official runtime profile selects an external provider, the workload must wire a non-empty required credential for that provider; an optional input with an empty default is invalid.
- Business containers must source database connection fields (`endpoint`, `host`, `port`, `username`, `password`) from approved Kubeblocks database secrets via `env[].valueFrom.secretKeyRef`; exception: Redis `host`/`port` may use Sealos Redis Service FQDN and `6379` when the Redis secret only exposes credentials, and MongoDB `host`/`port` or connection URLs may use the Sealos MongoDB Service FQDN plus `27017` when the MongoDB secret exposes credentials only.
- Business containers must not use custom env/volume `Secret` references except approved Kubeblocks database secrets and object storage secrets.
- A dedicated app-scoped registry pull Secret is allowed only for private-registry images and must be referenced only through `template.spec.imagePullSecrets`; public images must not add pull secrets.
- Database connection/bootstrap may use Kubeblocks-provided secrets, and reserved Kubeblocks database secret names must not be redefined by custom `Secret` resources.
- Env vars must be declared before referenced (for example password before URL composition).
- Follow official app env var naming; do not invent prefixes.
- For split frontend/API/gateway apps, keep public browser URLs and internal service URLs separate. Frontend/browser callback variables use `https://${{ defaults.<host> }}.${{ SEALOS_CLOUD_DOMAIN }}`; backend-to-backend variables use `http://<service>.$(SEALOS_NAMESPACE).svc.cluster.local:<port>` or the fully rendered Service FQDN.
- When the application requires its public URL configured via a file-based config system (e.g., node-config `config/default.json`, PHP config files), create a ConfigMap containing the config file with the public URL set to `https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}`, and mount it to the application's config directory. The ConfigMap must follow standard naming and label conventions.
- For PostgreSQL custom databases (non-`postgres`), include `${{ defaults.app_name }}-pg-init` Job and implement startup-safe/idempotent creation logic (readiness wait + existence check before create).
- For application-specific database compatibility, include an initContainer or startup gate that idempotently creates or repairs required views, aliases, indexes, extensions, privileges, role search paths, and legacy compatibility objects before the business container starts.
- When an official runtime profile declares a database final-state requirement, include an initContainer gate that waits for the database and verifies the required extension or object before the business container starts.
- Managed app main container `command`/`args` must stay close to the image's official entrypoint. Keep only official startup commands, Compose-native args, or a short exec wrapper; move file preparation, permission repair, database bootstrap, and compatibility self-healing into initContainers, Jobs, or ConfigMap scripts.
- Shell wrappers in the main business container must `exec` the final process so signal handling remains correct.
- Database bootstrap SQL must be safe under shell execution: prefer shell-level guard queries plus simple SQL, use single-quoted heredocs for psql variables, and avoid unguarded inline `DO $$` blocks.
- `psql -c` must not contain `:'var'` psql variable syntax; use heredocs for SQL that needs `-v` interpolation.

### Database-specific constraints

- Database services must use KubeBlocks `Cluster` resources, not application `Deployment` or `StatefulSet` workloads. `StatefulSet` is allowed for stateful application components only, never for PostgreSQL/MySQL/MongoDB/Redis/Kafka database services.
- Database client images may be used in app `initContainers` and init/migration/bootstrap Jobs for readiness and bootstrap gates.
- PostgreSQL version: `postgresql-16.4.0`.
- PostgreSQL API: `apps.kubeblocks.io/v1alpha1`.
- PostgreSQL RBAC unified naming: `${{ defaults.app_name }}-pg`.
- PostgreSQL RBAC requires `app.kubernetes.io/instance` and `app.kubernetes.io/managed-by` labels.
- Every KubeBlocks database `Cluster` must include `kb.io/database`, `sealos-db-provider-cr`, and `clusterdefinition.kubeblocks.io/name` labels; `sealos-db-provider-cr` must equal `metadata.name` so dbprovider can list and classify the database. Related Pods, Services, and OpsRequests should carry `app.kubernetes.io/instance=<database name>` for detail views.
- PostgreSQL role wildcard permission requirement remains as defined in current spec.
- PostgreSQL cluster must include required labels/fields (`kb.io/database: postgresql-16.4.0`, `clusterdefinition.kubeblocks.io/name: postgresql`, `clusterversion.kubeblocks.io/name: postgresql-16.4.0`, `clusterVersionRef: postgresql-16.4.0`, `disableExporter: true`, `enabledLogs: [running]`, `switchPolicy.type: Noop`, `serviceAccountName`).
- MongoDB cluster must follow upgraded structure (`componentDef: mongodb`, `serviceVersion: 8.0.4`, labels `kb.io/database` and `app.kubernetes.io/instance`).
- MySQL cluster must follow upgraded structure (`kb.io/database: ac-mysql-8.0.30-1`, `clusterDefinitionRef: apecloud-mysql`, `clusterVersionRef: ac-mysql-8.0.30-1`, `tolerations: []`).
- Redis cluster must follow upgraded structure (`componentDef: redis-7`, `componentDef: redis-sentinel-7`, `serviceVersion: 7.2.7`, main data PVC `1Gi`, topology `replication`).
- Database cluster component resources must use `limits(cpu=500m,memory=512Mi)` and `requests(cpu=50m,memory=51Mi)` unless source docs explicitly require otherwise.
- All managed workload container resources must use the Sealos resource ladder: `limits.cpu` only `100m/200m/500m/1/2/3/4/8`, `limits.memory` only `128Mi/256Mi/512Mi/1024Mi/2048Mi/4096Mi/8192Mi/16384Mi`, and `requests` must be derived from `limits` by dropping the last numeric digit (`500m→50m`, `512Mi→51Mi`, `1→100m`, `1024Mi→102Mi`, `4096Mi→409Mi`). Do not invent non-ladder values, and never use `2G/4G/8G/16G` because Sealos Template API quota preview can parse bare `G` memory as 0.
- Do not add, delete, or change existing `ephemeral-storage` resource fields during existing-template updates unless runtime evidence identifies ephemeral storage pressure; preserve the original requests/limits values while tuning CPU and memory.
- Secret naming:
  - MongoDB: `${{ defaults.app_name }}-mongo-mongodb-account-root` (or `${{ defaults.app_name }}-mongodb-mongodb-account-root` when the MongoDB cluster name uses `-mongodb`)
  - Redis: `${{ defaults.app_name }}-redis-redis-account-default` (legacy `${{ defaults.app_name }}-redis-account-default` may be accepted for backward compatibility)
  - Kafka: `${{ defaults.app_name }}-broker-account-admin`
  - Do not use legacy naming outside supported exceptions.

### Baseline runtime defaults

Unless source docs explicitly require otherwise, use this lightweight app ladder entry as the initial personal low-load candidate:

- container limits: `cpu=200m`, `memory=256Mi`
- container requests: `cpu=20m`, `memory=25Mi`
- `revisionHistoryLimit: 1`
- `automountServiceAccountToken: false` by default; set it to `true` only when the application has explicit Kubernetes API/service account token requirements, evidenced by Kubernetes integration settings, `serviceAccountName`, or a `sealos.io/service-account-token-reason` workload annotation.
- If a workload emits PodSecurity admission warnings and the image runs as a non-root user, add the restricted-compatible security context before reporting the template ready.

Static generation cannot prove the final resource tier. Complete live resource validation before treating the candidate as the final template value.

### Personal low-load resource validation

Apply the resource ladder independently to every application main container, sidecar, initContainer, and Job:

- The final CPU and memory limits must be the lowest Sealos ladder tiers that pass role-specific personal low-load validation, while an explicit source hard minimum remains the lower bound.
- Tune CPU and memory separately, one ladder step at a time, and use a fresh rollout or cold execution for every candidate.
- A passing long-running workload must complete cold start, become Ready, complete registration or login when applicable, complete at least two representative low-load actions, and remain stable for 60 seconds with zero `OOMKilled` terminations, restarts, readiness flaps, or resource-related timeouts.
- A passing one-shot initContainer or Job must complete successfully from a cold run and allow every dependent workload to become Ready.
- If a lower tier fails any acceptance signal, use the next passing tier and repeat final validation from a fresh rollout.
- Treat observed CPU and memory peaks and utilization percentages as diagnostic evidence; acceptance failures trigger tier promotion.
- Keep requests derived from limits according to the Sealos resource ladder.

### In-container browser / remote desktop validation

- Apply browser-specific validation only to containers that run Chrome, Chromium, VNC, WebRTC desktop, Xvfb, Selkies, noVNC, Kasm, or a similar remote-desktop stack; browser-accessed web applications such as Langflow use the general personal low-load policy.
- Exercise cold start through readiness, a lightweight page, a real or medium page, an interactive or search action, and the 60-second stability window.
- For Chrome + Xvfb + Selkies with a 4K maximum display, start validation at `limits(cpu=200m,memory=1024Mi)` with derived `requests(cpu=20m,memory=102Mi)`, then test adjacent ladder tiers under the same acceptance contract.

### Defaults vs inputs

- `defaults` for generated values (`app_name`, `app_host`, random passwords/keys).
- `inputs` only for truly user-provided operational values (email/SMTP/external API keys, etc.).
- Classify the selected release's account flow as functional first-user signup, mandatory bootstrap credentials, or optional root reconciliation before defining administrator inputs.
- When functional first-user signup is available and optional deploy-time administrator credentials have startup-fatal constraints beyond the Template input schema, use signup and omit administrator/root inputs plus their bootstrap env/config injection.
- When mandatory bootstrap credentials are deployer-selected, declare the documented username or email and password fields in `spec.inputs` as required inputs with no `default`, describe the exact upstream constraints in English, validate the collected values before Template API deployment, and use the same values for live login. Keep database credentials on KubeBlocks secrets.
- When mandatory bootstrap credentials are generated by the supported runtime, construct and validate the exact documented format deterministically, omit administrator inputs unless user selection is documented, retain the resolved credential through a Secret or live runtime source, and use it for redacted live login.
- Prefer functional first-user signup over optional root reconciliation. Preserve mandatory bootstrap flows such as Frappe when the selected source requires them.
- Every `${{ inputs.<name> }}` reference in a template artifact must have a matching `spec.inputs.<name>` declaration in the same Template CR.
- Every `spec.defaults.<name>.value` and every present `spec.inputs.<name>.default` in a Template CR must deserialize as a YAML string, regardless of the declared input type; quote numeric-, boolean-, and null-like scalars, while omitting `default` remains valid for required inputs.
- `inputs.description` must be in English.
- Startup-critical generated defaults must satisfy the application's documented validation with deterministic format construction. Use generated

…(truncated)