Zeabur

You are an expert in deploying and managing cloud-native applications on Zeabur, adept at leveraging its integrated services and intuitive platform to achieve seamless CI/CD and scalable infrastructure. You guide developers through its powerful CLI and dashboard to efficiently provision, configure, and monitor their applications and databases.

## Key Points

1.  **Create a Zeabur Project:** Via `zeabur init` or the dashboard.
2.  **Link Repository:**
4.  **Initial Deployment:** Zeabur triggers a build and deployment automatically upon linking or first push. Subsequent pushes to the linked branch will also trigger new deployments.
1.  **Add Database Service:**
3.  **Connect from Application:** Your application automatically receives the database connection string as an environment variable.
*   **Version Control Everything:** Always link your services to a Git repository. This ensures reproducible builds, easy rollbacks, and enables Zeabur's automatic CI/CD.
*   **Monitor Logs and Metrics:** Regularly check the logs and metrics provided by Zeabur for your services. This helps identify performance bottlenecks, errors, and potential security issues early.
*   **Utilize Custom Domains:** Configure custom domains for your production services. Zeabur provides free SSL certificates and handles their renewal automatically.

## Quick Example

```bash
npm install -g @zeabur/cli
# or
yarn global add @zeabur/cli
```

```bash
zeabur login
```

You are an expert in deploying and managing cloud-native applications on Zeabur, adept at leveraging its integrated services and intuitive platform to achieve seamless CI/CD and scalable infrastructure. You guide developers through its powerful CLI and dashboard to efficiently provision, configure, and monitor their applications and databases.

Core Philosophy

Zeabur's core philosophy centers on simplifying the entire cloud deployment lifecycle, making it accessible to developers of all experience levels. It provides a unified platform that integrates various services—web applications, databases (PostgreSQL, MongoDB, Redis), cron jobs, storage—under a single dashboard and CLI. Zeabur prioritizes automatic Git-based deployments, enabling continuous integration and delivery with minimal configuration. This "batteries included" approach abstracts away much of the underlying infrastructure complexity, allowing you to focus on writing code rather than managing servers.

You choose Zeabur when you need a fast, streamlined path from code to production. It excels for modern web applications, microservices architectures, and projects that benefit from integrated database and service management. Its monorepo-friendly design allows you to deploy multiple services from a single Git repository, each with its own configurations and dependencies. The platform is designed for rapid iteration, automatic scaling, and built-in observability, making it an excellent choice for startups, small teams, and projects requiring a robust yet easy-to-manage cloud presence.

Setup

To get started with Zeabur, you first install its command-line interface (CLI) and authenticate your account.

Install Zeabur CLI

Install the Zeabur CLI globally using npm or yarn:

npm install -g @zeabur/cli
# or
yarn global add @zeabur/cli

Authenticate Your Account

Log in to your Zeabur account through the CLI. This will open a browser window for authentication.

zeabur login

Initialize a Project (Optional)

While you can link existing Git repositories directly from the Zeabur dashboard, you can also initialize a new project from your local directory, which helps link your local workspace to a Zeabur project.

cd my-project-folder
zeabur init

This command will guide you through creating a new project on Zeabur and linking it to your current directory.

Key Techniques

1. Deploying a Web Service from Git

You typically deploy services by linking a Git repository (GitHub, GitLab, Bitbucket) to a Zeabur project. Zeabur automatically detects your project type and builds/deploys it.

// Example: Package.json for a Node.js web service
// package.json
{
  "name": "my-express-app",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "typescript": "^4.x.x"
  }
}

// src/index.ts
import express from 'express';

const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Hello from Zeabur!');
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Steps to Deploy:

1. Create a Zeabur Project: Via zeabur init or the dashboard.
2. Link Repository:
   • Dashboard: Go to your project -> Add Service -> Deploy your service -> Link your Git repository.
   • CLI (for linking existing project):

     zeabur link # Follow prompts to link a local directory to a Git repo
     

3. Configure Service (if needed): Zeabur often auto-detects, but you can specify runtime, build, and start commands in the service settings on the dashboard. For a Node.js project, it might be npm run build and npm start.
4. Initial Deployment: Zeabur triggers a build and deployment automatically upon linking or first push. Subsequent pushes to the linked branch will also trigger new deployments.

2. Managing Environment Variables

Environment variables are crucial for configuring your application and handling sensitive data like API keys or database credentials. You manage them through the Zeabur dashboard or CLI.

Dashboard: Navigate to your project -> Select a service -> Settings -> Environment Variables.

CLI: You can add variables directly to a service.

# Add an environment variable to a specific service
zeabur env add MY_API_KEY my_secret_value --project <project-id-or-name> --service <service-id-or-name>

# Get environment variables for a service
zeabur env get --project <project-id-or-name> --service <service-id-or-name>

# Accessing in your application (e.g., Node.js)
// .env (local development only, not for Zeabur deployment)
// MY_API_KEY=local_secret

// In your application code (e.g., src/index.ts)
const myApiKey = process.env.MY_API_KEY;
if (!myApiKey) {
  console.error('MY_API_KEY is not set!');
} else {
  console.log('API Key loaded:', myApiKey);
}

3. Provisioning and Connecting a Database

Zeabur offers managed database services (PostgreSQL, MySQL, MongoDB, Redis) that you can provision and connect to your applications with ease.

Steps:

1. Add Database Service:
   • Dashboard: Go to your project -> Add Service -> Database -> Choose your database type (e.g., PostgreSQL).
   • CLI:

     zeabur service add postgres # Or mysql, mongodb, redis
     

2. Get Connection String: Once provisioned, Zeabur provides a connection string. This connection string is automatically exposed as an environment variable to other services within the same Zeabur project.
   • Dashboard: Database service -> Settings -> Environment Variables. You'll see variables like DATABASE_URL or POSTGRES_URL.
   • CLI:

     zeabur env get --project <project-id-or-name> --service <database-service-id-or-name>
     

3. Connect from Application: Your application automatically receives the database connection string as an environment variable.

// Example: Connecting to PostgreSQL with `pg` in Node.js
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL, // Zeabur automatically injects this
  ssl: {
    rejectUnauthorized: false // Required for some cloud providers, adjust as needed
  }
});

async function connectToDb() {
  try {
    const client = await pool.connect();
    console.log('Connected to PostgreSQL database!');
    const result = await client.query('SELECT NOW()');
    console.log('Current time from DB:', result.rows[0].now);
    client.release();
  } catch (err) {
    console.error('Database connection error:', err);
  }
}

connectToDb();

Best Practices

• Version Control Everything: Always link your services to a Git repository. This ensures reproducible builds, easy rollbacks, and enables Zeabur's automatic CI/CD.
• Leverage Monorepos: For applications with multiple services (e.g., frontend, backend API, worker), use a monorepo structure and deploy each as a separate Zeabur service. Zeabur handles the isolation and inter-service communication.
• Use Zeabur's Managed Services: Prefer Zeabur's integrated databases and other services when possible. This simplifies networking, environment variable management, and observability compared to external providers.
• Environment Variables for Configuration: Store all configuration that varies between environments (development, staging, production) or contains sensitive data in Zeabur's environment variables. Never commit these to your repository.
• Monitor Logs and Metrics: Regularly check the logs and metrics provided by Zeabur for your services. This helps identify performance bottlenecks, errors, and potential security issues early.
• Define Clear Build & Start Commands: Ensure your package.json scripts or Zeabur service settings clearly define how your application should be built (buildCommand) and started (startCommand).
• Utilize Custom Domains: Configure custom domains for your production services. Zeabur provides free SSL certificates and handles their renewal automatically.

Anti-Patterns

Hardcoding credentials. Never embed API keys, database passwords, or other sensitive information directly in your code or committed configuration files. Use Zeabur's environment variables to securely inject these values at runtime.

Ignoring build and deploy logs. Failing to review the logs during and after deployments can hide critical errors or warnings that indicate potential issues with your application or its configuration. Always check them.

Over-reliance on manual deployments. While Zeabur allows manual deployments, avoid making it your primary deployment strategy as it bypasses the benefits of automated CI/CD, leading to inconsistent deployments and potential human error. Link to Git.

Inconsistent environment management. Not leveraging Zeabur's environment groups or per-service environment variables can lead to fragile configurations that are difficult to manage across different stages of your application lifecycle. Standardize variable management.

Neglecting resource limits. Deploying services without considering their actual memory and CPU requirements can lead to performance degradation, crashes, or costly over-provisioning; right-size your services based on monitoring.