template: PREBUILT_V2

template: GIT

ARBITRARY_GIT

GITHUB

1. Clone the project repo and find its

   Dockerfile

   (usually at repo root)
2. Study the Dockerfile to understand build stages — use the production stage (often named

   runner

   or

   production

   )
3. 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
4. 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 .

5. 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.

• 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

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

1. Search for existing templates that already use that service:
   bash

   npx zeabur@latest template search postgres

2. Find a template that includes the service you need
3. Get the raw template YAML to see the exact service definition:
   bash

   npx zeabur@latest template get -c TEMPLATE_CODE --raw

4. Copy the service definition directly from that template into yours

• 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

npx zeabur@latest template deploy -f YOUR_TEMPLATE.yaml

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

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

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

docker exec

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

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

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

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.

npx zeabur@latest template create -f YOUR_TEMPLATE.yaml

https://zeabur.com/templates/XXXXXX

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

• name: app spec: env: DB: ${POSTGRES_HOST}

• name: app dependencies:
  • postgresql spec: env: DB: ${POSTGRES_HOST}

---

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

• Database service exposes vars, app service references them
• App service uses

  dependencies

  to ensure DB starts first

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

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

• 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

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

1. 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
2. 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
3. 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

   ).

1. Read the project's

   Dockerfile

   to understand the build stages and the final

   CMD

   /

   ENTRYPOINT

2. 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
3. Check the app's

   package.json

   scripts to understand what

   yarn start

   or

   npm start

   actually runs
4. The startup command in docker-compose is battle-tested -- copy it, don't reinvent it

• 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

• 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

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

• 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

• icon

  URL

• coverImage

  URL
• Links in

  readme

raw.githubusercontent.com

develop

main

master

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