mcpField
Z
zeabur-startup-order

zeabur-startup-order

github.com/zeaburCloud & DevOps39175 installsUpdated 7w ago
Repository

About zeabur-startup-order

zeabur-startup-order is a troubleshooting skill for Zeabur deployments where an app starts before its database or Redis is ready. It explains how to address startup order with dependency health checks or wait logic in the app command.

Key features

  1. 01Identify dependency readiness errors
  2. 02Configure TCP health checks for databases
  3. 03Configure TCP health checks for Redis
  4. 04Add a wait loop to startup commands
  5. 05Restart a failed service

Use cases

  1. 01Troubleshoot refused database connections
  2. 02Prevent apps starting before Redis is ready
  3. 03Recover services that failed on unavailable dependencies

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/zeabur/agent-skills --skill zeabur-startup-order

After installing, type/zeabur-startup-orderin Claude Code to confirm it loaded.

Details

From the project README

Zeabur Startup Order Issues

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.

Symptom

Connection refused :5432
connection to server at "X" failed
OperationalError: connection failed

Cause

Service starts before dependency (DB/Redis) is ready. dependencies only ensures container start order, NOT that the service is accepting connections.

Fix (Recommended): healthCheck on dependency services

Add healthCheck to database/Redis services so Zeabur waits until the port is accepting connections before starting dependent services — no need to modify the app's command.

Edit the template YAML (use the zeabur-template skill for YAML reference):

- name: postgresql
  spec:
    ports:
      - id: database
        port: 5432
        type: TCP
    healthCheck:
      type: TCP
      port: database    # references the port ID above

- name: redis
  spec:
    ports:
      - id: database
        port: 6379
        type: TCP
    healthCheck:
      type: TCP
      port: database

Fix (Alternative): Wait loop in command

If you can't modify the template (use the zeabur-template skill), add wait logic to the app's command (command MUST be inside source):

spec:
  source:
    image: myapp:latest
    command:
      - /bin/sh
      - -c
      - "until nc -z postgres 5432; do sleep 1; done && node server.js"

Quick Fix

If DB is now ready, just restart the failed service:

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

If the issue is specifically about database migration waiting loops rather than startup order, use the zeabur-migration skill.

Comments

Markdown supported