Always use

npx zeabur@latest

to invoke Zeabur CLI. Never use

zeabur

directly or any other installation method. If

npx

is not available, install Node.js first.

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

domainKey

1. Use

   type: TCP

   (or

   UDP

   ) — this prevents Zeabur's reverse proxy (Ingress) from intercepting traffic
2. Set

   portForwarding: enabled: true

   — this auto-exposes the port externally so clients can connect directly
3. Do NOT use

   domainKey

   — TCP services don't need a domain; users connect via the forwarded hostname:port

undefined

Missing portForwarding — users must manually enable in Dashboard

**Why not HTTP?** Zeabur's HTTP port type routes traffic through a reverse proxy (Ingress/Envoy) that terminates TLS and performs Host-based routing. This breaks protocols like HTTP CONNECT (used by proxies), raw TCP streams (databases), and custom binary protocols (game servers).

**Port Forwarding variables** (for use in `instructions` or readme):
- `${PORT_FORWARDED_HOSTNAME}` — the external hostname
- `${PROXY_PORT_FORWARDED_PORT}` — the external port (pattern: `${[PORTID]_PORT_FORWARDED_PORT}`)

**Post-deployment testing for TCP services:**

After deploying a TCP service, verify port forwarding is working:

1. Check internal connectivity first (from inside the container):
   ```bash
   npx zeabur@latest service exec --id SERVICE_ID -- curl -x http://127.0.0.1:8888 https://ifconfig.co

1. Get the forwarded host:port from the Dashboard's Networking tab, or use:
   bash

   npx zeabur@latest service network --id SERVICE_ID

2. Test external connectivity:
   bash

   curl -x http://FORWARDED_HOST:FORWARDED_PORT https://ifconfig.co

npx zeabur@latest service port-forward --id SERVICE_ID --enable

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

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

• id: proxy port: 8888 type: HTTP

• id: proxy port: 8888 type: TCP portForwarding: enabled: true

---

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

   ).