Zeabur Template Knowledge Base

This skill provides comprehensive knowledge for creating, debugging, and publishing Zeabur templates. It combines reference documentation with battle-tested patterns from real template development.

External Documentation

For the latest schema and detailed docs, fetch from

https://raw.githubusercontent.com/zeabur/zeabur-template-doc/main/

User Need	Document to Fetch	Path
Create a template from scratch	Step-by-step guide	`docs/GUIDE.md`
Convert docker-compose.yml	Migration guide	`docs/DOCKER_COMPOSE_MIGRATION.md`
Look up YAML fields or built-in variables	Technical reference	`docs/REFERENCE.md`
Naming, design patterns, best practices	Best practices	`docs/BEST_PRACTICES.md`
Debug template errors	Troubleshooting	`docs/TROUBLESHOOTING.md`
Pre-deployment checklist	Checklist	`docs/CHECKLIST.md`
Quick all-in-one overview	Comprehensive prompt	`prompt.md`

The template YAML schema is also available at https://schema.zeabur.app/template.json and the prebuilt service schema at https://schema.zeabur.app/prebuilt.json.

Core Principles

0. All services MUST use PREBUILT_V2 with Docker images

Every service in a template MUST be
template: PREBUILT_V2
with a Docker image as the source. Never use

template: GIT

ARBITRARY_GIT

, or

GITHUB

source — these are NOT supported in templates.

If the project does not have a published Docker image (on Docker Hub, GHCR, etc.), tell the user they need to build and publish a Docker image first before a template can be created. Do not attempt to work around this.

If the user asks you to build the image, follow this workflow:

Clone the project repo and find its
```
Dockerfile
```
(usually at repo root)
Study the Dockerfile to understand build stages — use the production stage (often named
```
runner
```
or
```
production
```
)
Study
```
docker-compose.yml
```
or
```
docker-compose.fullapp.yml
```
for the correct startup command, env vars, and volumes — this is the battle-tested production config

Build for amd64 (Zeabur servers are amd64, local Macs are arm64):

bash

docker buildx build --platform linux/amd64 --target runner -t org/image:tag --push .

After pushing, verify the Docker Hub repo is public:
bash
```
curl -s "https://hub.docker.com/v2/repositories/ORG/IMAGE/" | grep is_private
```
New repos under org accounts often default to private. If
```
is_private: true
```
, the user must make it public on Docker Hub.

1. Never start from scratch

When asked to create a template, always look for existing configuration first:

First check if a Docker image exists — search Docker Hub, GHCR (
```
ghcr.io/org/repo
```
), or the project's CI/CD for published images. If none exists, stop and inform the user.

Search for the project's

docker-compose.yml

docker-compose.yaml

, or

compose.yml

Look for Helm charts (
```
Chart.yaml
```
,
```
values.yaml
```
)
Check the project's GitHub repo for any deployment YAML files
Use these as the foundation to build the Zeabur template, not as a loose reference — they contain battle-tested environment variables, port mappings, volume mounts, and service dependencies

2. Iterate via runtime logs — never expect one-shot success

Even experienced humans cannot create a working template in one shot. The workflow is an iterative loop:

Write/update the template YAML
Deploy the template
It will likely fail — check runtime logs to find the cause
Fix the issue in the template
Delete the project and redeploy from scratch
Repeat until the template achieves one-click deployment success

This is the normal process, not a sign of failure. Do not try to get everything perfect before deploying — deploy early, read logs, and iterate.

3. Reuse from existing templates — never write common services from scratch

When your template needs a common service (PostgreSQL, Redis, MySQL, MongoDB, etc.), do not write the service definition yourself. Instead:

Search for existing templates that already use that service:
bash
```
npx zeabur@latest template search postgres
```
Find a template that includes the service you need
Get the raw template YAML to see the exact service definition:
bash
```
npx zeabur@latest template get -c TEMPLATE_CODE --raw
```
Copy the service definition directly from that template into yours

How to judge template trustworthiness:

Many templates are created by regular users and may not work correctly
Prefer templates with more deployments — higher deployment count = more battle-tested
Prefer official templates over user-submitted ones — official templates are vetted by Zeabur team

CLI Commands for the Iteration Loop

Deploy a template:

bash

npx zeabur@latest template deploy -f YOUR_TEMPLATE.yaml

For non-interactive mode (automation):

bash

npx zeabur@latest template deploy -i=false \
  -f YOUR_TEMPLATE.yaml \
  --project-id PROJECT_ID \
  --var PUBLIC_DOMAIN=myapp

List services (to get SERVICE_ID):

bash

npx zeabur@latest service list --project-id PROJECT_ID

Check runtime logs:

bash

npx zeabur@latest deployment log --service-id SERVICE_ID

Execute a command inside a running service (like

docker exec

bash

npx zeabur@latest service exec --id SERVICE_ID -- SHELL_COMMAND

This is extremely useful for debugging — check file paths, env vars, test connectivity, inspect the filesystem, etc. Examples:

bash

npx zeabur@latest service exec --id SERVICE_ID -- ls /app
npx zeabur@latest service exec --id SERVICE_ID -- env | grep DATABASE
npx zeabur@latest service exec --id SERVICE_ID -- nc -z localhost 5432

Restart a service (useful to clear ImagePullBackOff or force re-pull):

bash

npx zeabur@latest service restart --id SERVICE_ID -i=false -y

Delete the project and start over:

bash

npx zeabur@latest project delete --id PROJECT_ID

DANGEROUS OPERATION — Before deleting a project, you MUST ask the user for explicit confirmation, clearly stating the Project ID, Name, and createdAt timestamp. Never delete without confirmation.

Publish a new template:

bash

npx zeabur@latest template create -f YOUR_TEMPLATE.yaml

This returns a template URL like

https://zeabur.com/templates/XXXXXX

with a template code.

Update an existing template:

bash

npx zeabur@latest template update -c TEMPLATE_CODE -f YOUR_TEMPLATE.yaml

Quick Reference: Template Skeleton

yaml

# yaml-language-server: $schema=https://schema.zeabur.app/template.json
apiVersion: zeabur.com/v1
kind: Template
metadata:
  name: ServiceName
spec:
  description: |
    English description (1-3 sentences)
  icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/service.svg
  coverImage: https://example.com/cover.webp
  tags:
    - Category
  variables: []
  readme: |
    # Service Name
    English documentation...
  services:
    - name: service-name
      icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/service.svg
      template: PREBUILT_V2
      spec:
        source:
          image: image:tag
          command:              # MUST be inside source, alongside image
            - /bin/sh
            - -c
            - /opt/app/startup.sh
        ports:
          - id: web
            port: 8080
            type: HTTP
        volumes:
          - id: data
            dir: /path/to/data
        configs:
          - path: /opt/app/startup.sh
            permission: 493     # 0755
            envsubst: false
            template: |
              #!/bin/sh
              exec node server.js
        env:
          VAR_NAME:
            default: value
            expose: true
localization:
  zh-TW:
    description: ...
    variables: []
    readme: |
      # ...
  zh-CN:
    description: ...
    variables: []
    readme: |
      # ...
  ja-JP:
    description: ...
    variables: []
    readme: |
      # ...
  es-ES:
    description: ...
    variables: []
    readme: |
      # ...
  id-ID:
    description: ...
    variables: []
    readme: |
      # ...

Quick Reference: Built-in Variables

Variable	Purpose
`${PASSWORD}`	Auto-generated secure password
`${ZEABUR_WEB_URL}`	Full public URL (e.g. `https://app.zeabur.app` )
`${ZEABUR_WEB_DOMAIN}`	Domain only (e.g. `app.zeabur.app` )
`${CONTAINER_HOSTNAME}`	Internal hostname for inter-service communication
`${[PORTID]_PORT}`	Port value by port ID (e.g. `${DATABASE_PORT}` )
`${PORT_FORWARDED_HOSTNAME}`	External hostname (for `instructions` )
`${[PORTID]_PORT_FORWARDED_PORT}`	External forwarded port (for `instructions` )

The

ZEABUR_<PORT_ID>_URL

pattern: for a port named

web

, it becomes

${ZEABUR_WEB_URL}

; for

console

, it becomes

${ZEABUR_CONSOLE_URL}

Quick Reference: command Placement

IMPORTANT:
command
MUST be inside
source
, alongside
image
. NOT at
spec
level.

yaml

# WRONG -- command at spec level (will be IGNORED, container uses default CMD)
spec:
  source:
    image: python:3.12-slim
  command:
    - /bin/sh
    - -c
    - /opt/app/start.sh

# CORRECT -- command inside source
spec:
  source:
    image: python:3.12-slim
    command:
      - /bin/sh
      - -c
      - /opt/app/start.sh

Note: The external docs may show
command
at
spec
level. This is incorrect. Always place
command
inside
source
as confirmed by the JSON schema at
schema.zeabur.app/prebuilt.json
.

Quick Reference: YAML Gotchas

yaml

# RISKY -- @ at start of value is a YAML reserved indicator (may cause parse errors)
description: @BotFather token

# SAFE -- quote the value or avoid @ at start
description: "Token from @BotFather for Telegram bot"
description: Telegram bot token from BotFather

Quick Reference: Docker Image ENTRYPOINT

Some base images have ENTRYPOINT set, which conflicts with
command
.

Image	ENTRYPOINT	Problem
`ghcr.io/astral-sh/uv:python3.12-*`	`uv`	`command` becomes args to `uv` , container shows `uv help` and exits
`node:*`	none	Safe to use
`python:*`	none	Safe to use

If using an image with ENTRYPOINT, switch to a plain base image (e.g.

python:3.12-slim-bookworm

) or one without ENTRYPOINT.

Quick Reference: Headless Services (no HTTP)

If a service does NOT listen on any HTTP port (502 Bad Gateway), see

zeabur-port-mismatch

skill for the fix.

Quick Reference: Critical Rules

yaml

# WRONG -- hardcoded password
POSTGRES_PASSWORD:
  default: mypassword123

# CORRECT -- use ${PASSWORD}
POSTGRES_PASSWORD:
  default: ${PASSWORD}
  expose: true

# WRONG -- PUBLIC_DOMAIN gives incomplete URL
APP_URL:
  default: https://${PUBLIC_DOMAIN}

# CORRECT -- ZEABUR_WEB_URL gives full URL
APP_URL:
  default: ${ZEABUR_WEB_URL}
  readonly: true

# WRONG -- other services can't reference without expose
POSTGRES_HOST:
  default: ${CONTAINER_HOSTNAME}

# CORRECT -- expose + readonly for connection info
POSTGRES_HOST:
  default: ${CONTAINER_HOSTNAME}
  expose: true
  readonly: true

# WRONG -- referencing variables without declaring dependency
- name: app
  spec:
    env:
      DB: ${POSTGRES_HOST}

# CORRECT -- declare dependency first
- name: app
  dependencies:
    - postgresql
  spec:
    env:
      DB: ${POSTGRES_HOST}

Domain Binding

Use

domainKey

on the service that needs a public domain. It maps to a variable defined in

spec.variables

with

type: DOMAIN

Single domain:

yaml

domainKey: PUBLIC_DOMAIN

Multiple domains (different ports):

yaml

domainKey:
    - port: web
      variable: ENDPOINT_DOMAIN
    - port: console
      variable: ADMIN_ENDPOINT_DOMAIN

Common Database Configs

PostgreSQL

yaml

- name: postgresql
  icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/postgresql.svg
  template: PREBUILT_V2
  spec:
    source:
      image: postgres:16-alpine
    ports:
      - id: database
        port: 5432
        type: TCP
    volumes:
      - id: data
        dir: /var/lib/postgresql/data
    env:
      POSTGRES_USER:
        default: postgres
        expose: true
      POSTGRES_PASSWORD:
        default: ${PASSWORD}
        expose: true
      POSTGRES_DB:
        default: mydb
        expose: true
      POSTGRES_HOST:
        default: ${CONTAINER_HOSTNAME}
        expose: true
        readonly: true
      POSTGRES_PORT:
        default: ${DATABASE_PORT}
        expose: true
        readonly: true
      POSTGRES_CONNECTION_STRING:
        default: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
        expose: true
        readonly: true

MySQL/MariaDB

yaml

- name: mariadb
  icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/mariadb.svg
  template: PREBUILT_V2
  spec:
    source:
      image: mariadb:10.6
    ports:
      - id: database
        port: 3306
        type: TCP
    volumes:
      - id: data
        dir: /var/lib/mysql
    env:
      MYSQL_ROOT_PASSWORD:
        default: ${PASSWORD}
        expose: true
      MYSQL_DATABASE:
        default: mydb
        expose: true
      MYSQL_HOST:
        default: ${CONTAINER_HOSTNAME}
        expose: true
        readonly: true
      MYSQL_PORT:
        default: ${DATABASE_PORT}
        expose: true
        readonly: true

Redis

yaml

- name: redis
  icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/redis.svg
  template: PREBUILT_V2
  spec:
    source:
      image: redis:7-alpine
    ports:
      - id: database
        port: 6379
        type: TCP
    volumes:
      - id: data
        dir: /data
    env:
      REDIS_HOST:
        default: ${CONTAINER_HOSTNAME}
        expose: true
        readonly: true
      REDIS_PORT:
        default: ${DATABASE_PORT}
        expose: true
        readonly: true

Standard Volume Paths

Service	Path
PostgreSQL	`/var/lib/postgresql/data`
MySQL/MariaDB	`/var/lib/mysql`
MongoDB	`/data/db`
Redis	`/data`
MinIO	`/data`

Template Complexity Levels

Level 1 -- Single prebuilt service (e.g., Memos, Uptime-Kuma, LobeChat):

Just one service with image, port, and optionally a volume
Simplest pattern, no cross-service wiring needed

Level 2 -- App + database (e.g., Ghost+MySQL, Linkwarden+PostgreSQL):

Database service exposes vars, app service references them
App service uses
```
dependencies
```
to ensure DB starts first

Level 3 -- App + database + init/migrator (e.g., Teable, Open Mercato):

First-run initialization or separate migrator service
Requires wait-for-db pattern and init marker files

Level 4 -- Multi-service with multiple domains (e.g., Logto):

Multiple ports on one service, each bound to a different domain variable

Level 5 -- Large-scale multi-service platform (e.g., Dify 12 services, Supabase 11 services):

Reverse proxy as entry point: nginx (Dify) or Kong (Supabase) as the single domain-bound service
Same image, different MODE: e.g., Dify runs
```
api
```
,
```
worker
```
,
```
worker-beat
```
from the same image
Internal-only services: no public domain, communicate via
```
${CONTAINER_HOSTNAME}
```
Heavy use of
configs
: Nginx conf, SQL init scripts, Kong config — all injected via
```
configs
```
field
PostgreSQL init SQL via configs: Mount to
```
/docker-entrypoint-initdb.d/
```
for auto execution
Shared secrets: Use
```
${PASSWORD}
```
for all internal credentials

Writing name, description, readme, icon, and coverImage

Where to collect information (in priority order):

The project's GitHub repo README
The project's official website
Other public sources (blog posts, documentation sites, etc.)

Key rules:

Do NOT copy-paste the original README. Write the introduction for this project's Zeabur template, not for the project itself. The readme should:
- Briefly introduce what the project is
- Focus on how to use this template (deployment steps, configuration, domain binding)
- Include important caveats and troubleshooting tips specific to Zeabur deployment
Always include licensing and attribution. If the original project has an MIT, Apache, or other license:
- Mention the license in the readme
- Link to the original repo
- Link to the official website if available
- This is legally required -- never skip it
icon and coverImage: Find the project's logo from their GitHub repo or official website. Use a direct URL to an image (SVG, PNG, or WebP). Always verify the URL returns HTTP 200:
bash
```
curl -s -o /dev/null -w "%{http_code}" "URL"
```
Common pitfall: wrong branch name in
```
raw.githubusercontent.com
```
URLs (
```
develop
```
vs
```
main
```
vs
```
master
```
).

Localization Requirements

6 languages required: en-US (in

spec

), zh-TW, zh-CN, ja-JP, es-ES, id-ID.

Translate:

description

variables[].name

variables[].description

readme

Do NOT translate:

key

type

${VARIABLE_NAMES}

, URLs

Hard-Won Lessons (from real template challenges)

Wait for database readiness

Zeabur's

dependencies

field only ensures services are deployed, not that they're ready to accept connections. A database container can take 5-15 seconds to initialize. Always add a wait loop before running migrations or init:

yaml

args:
    - -c
    - |
        echo "Waiting for PostgreSQL..."
        while ! nc -z ${POSTGRES_HOST} ${POSTGRES_PORT} 2>/dev/null; do sleep 2; done
        echo "PostgreSQL is ready!"
        echo "Waiting for Redis..."
        while ! nc -z ${REDIS_HOST} ${REDIS_PORT} 2>/dev/null; do sleep 2; done
        echo "Redis is ready!"
        # ... then run migrations/init

Note:

nc

(netcat) is available on most Alpine-based images. If not, use

wget --spider

or a node one-liner.

Study the project's own Dockerfile and docker-compose

Never guess startup commands. Instead:

Read the project's
```
Dockerfile
```
to understand the build stages and the final
```
CMD
```
/
```
ENTRYPOINT
```
Read
```
docker-compose.yml
```
and especially
```
docker-compose.fullapp.yml
```
(or
```
docker-compose.prod.yml
```
) for the production startup command -- these often override the Dockerfile's CMD with init/migrate logic
Check the app's
```
package.json
```
scripts to understand what
```
yarn start
```
or
```
npm start
```
actually runs
The startup command in docker-compose is battle-tested -- copy it, don't reinvent it

Memory-heavy apps need lighter startup

Apps that spawn workers, schedulers, and the web server all in one process may OOM on Zeabur's default allocation. Signs of OOM:

Container starts, runs for 1-2 minutes, then crashes with no error logs (just
```
BackOff: Back-off restarting failed container
```
)
No application-level crash message -- the kernel kills the process silently

Solutions:

Run the web server directly (e.g.,
```
next start
```
or
```
node server.js
```
) instead of a CLI wrapper that spawns workers + scheduler + server
Disable non-essential background processes via env vars (e.g.,
```
AUTO_SPAWN_WORKERS=false
```
)
If workers are needed, consider splitting them into a separate service

First-run init with persistent marker

For apps that need first-time initialization (DB schema, seed data, admin users), use a marker file in a persistent volume:

yaml

args:
    - -c
    - |
        if [ ! -f /app/storage/.initialized ]; then
          echo "First run: initializing..."
          run-init-command && touch /app/storage/.initialized
        else
          echo "Subsequent run: migrations only..."
          run-migrate-command
        fi
        exec start-server-command

Key points:

The marker file MUST be in a persistent volume, not
```
/tmp/
```
(which is ephemeral)
Use
```
&&
```
after init so the marker is only created if init succeeds
Use
```
exec
```
for the final server process so it becomes PID 1 and receives signals properly
Read init logs carefully for the actual default credentials -- don't assume from docs

Working directory matters

When overriding

command

args

, be aware of the Dockerfile's

WORKDIR

. In monorepo apps, different commands need to run from different directories:

yaml

args:
    - -c
    - |
        cd /app              # root workspace for yarn workspace commands
        yarn mercato init    # CLI from root package.json
        cd /app/apps/myapp   # app directory for next start
        exec next start -p 3000

ImagePullBackOff recovery

When a pod is stuck in

ImagePullBackOff

(e.g., after making a Docker Hub repo public), the Kubernetes backoff timer prevents immediate retries. Fix by restarting the service:

bash

npx zeabur@latest service restart --id SERVICE_ID -i=false -y

Disable unused monitoring agents

Many production images ship with New Relic, Datadog, or similar APM agents. These require license keys and consume memory. Add

NEW_RELIC_ENABLED=false

or equivalent env vars to disable them cleanly. Check if the

start

script injects agents via

NODE_OPTIONS='-r newrelic'

-- these still run even if the agent errors out.

Verify all URLs before publishing

Before publishing a template, verify that ALL URLs return HTTP 200:

```
icon
```
URL
```
coverImage
```
URL
Links in
```
readme
```

Common pitfall:

raw.githubusercontent.com

URLs with wrong branch name (

develop

main

master

). Always check:

bash

curl -s -o /dev/null -w "%{http_code}" "https://raw.githubusercontent.com/..."

zeabur-template

NPX Install

Tags

SKILL.md Content

Zeabur Template Knowledge Base

External Documentation

Core Principles

0. All services MUST use PREBUILT_V2 with Docker images

1. Never start from scratch

2. Iterate via runtime logs — never expect one-shot success

3. Reuse from existing templates — never write common services from scratch

CLI Commands for the Iteration Loop

Quick Reference: Template Skeleton

Quick Reference: Built-in Variables

Quick Reference: command Placement

Quick Reference: YAML Gotchas

Quick Reference: Docker Image ENTRYPOINT

Quick Reference: Headless Services (no HTTP)

Quick Reference: Critical Rules

Domain Binding

Common Database Configs

PostgreSQL

MySQL/MariaDB

Redis

Standard Volume Paths

Template Complexity Levels

Writing name, description, readme, icon, and coverImage

Localization Requirements

Hard-Won Lessons (from real template challenges)

Wait for database readiness

Study the project's own Dockerfile and docker-compose

Memory-heavy apps need lighter startup

First-run init with persistent marker

Working directory matters

ImagePullBackOff recovery

Disable unused monitoring agents

Verify all URLs before publishing