Declarative Deployment (tcb deploy)

Version Requirement

tcb deploy declarative orchestration is available since v3.8.0 and requires cloudbaserc.json v2.1.

tcb deploy reads cloudbaserc.json (v2.1) in the project root and orchestrates deployment of cloud functions, cloud apps, static hosting, gateway routes, and database migrations in dependency order — no need to call single-resource commands one by one.

First time using CloudBase CLI?

Read the Quick Start first: install the CLI, log in to your account, and generate cloudbaserc.json, then come back to this page to use tcb deploy.

Differences from Single-Resource Commands

Dimension	tcb deploy	tcb fn deploy / tcb hosting deploy
Config source	One cloudbaserc.json declares all resources	Each command passes its own arguments
Orchestration	database → functions → app → hosting → gateway auto-ordered	Single resource
Dependencies	Functions depend on new Schema (database first), gateway depends on functions/hosting	Not aware
Idempotency	Cloud existence check; every deploy is executed	Full execution every time
Overwrite confirmation	Confirms before overwriting existing functions (--yes to proceed)	--force

Complete Workflow

The standard end-to-end workflow for declarative deployment: Initialize Configuration → validate → build → preview changes → deploy.

Step	Command	Purpose	Completion Signal
1 Initialize config	tcb config init	Auto-detects project resources (cloud function dirs / frontend framework / static hosting dirs) and interactively generates cloudbaserc.json (v2.1)	Valid config created in the project root
2 Validate before deploy	tcb validate	Validates schema version / envId / resource dirs / reference consistency	Exit code 0, resource overview printed
3 Build	tcb app build	Builds static hosting (hosting[]) output locally into outputDir; only needed for sites with buildCommand configured — pure-static sites can skip	Output generated in outputDir
4 Preview changes	tcb deploy --dry-run	Outputs the resource-level change plan: field-level diffs (from → to) — no actual deployment	Change plan matches expectations
5 Deploy	tcb deploy	Orchestrates deployment in database → functions → app → hosting → gateway order (static hosting only uploads build output)	Deployment succeeds

Build and deploy are separated

Since CLI v3.8.2, tcb deploy no longer runs local builds or installs dependencies for static hosting. tcb deploy only deploys:

• For static hosting (hosting), first run tcb app build (runs buildCommand locally, does not install dependencies), then run tcb deploy to upload the output
• If a hosting item configures buildCommand but the output directory does not exist, tcb deploy errors and prompts you to run tcb app build first
• Cloud functions (functions) dependencies are installed in the cloud (or via image builds), no local build needed
• Pure-static hosting (no buildCommand) uploads root/outputDir directly, no build needed

tcb app build        # build hosting[] locally (output goes to outputDir)
tcb deploy           # upload output and orchestrate the remaining resources

Configuration Example

Minimal cloudbaserc.json (v2.1):

{
  "envId": "your-env-id",
  "version": "2.1",
  "functions": [
    { "name": "pay-common", "type": "Event", "handler": "index.main" }
  ],
  "hosting": [
    {
      "name": "web",
      "root": "web",
      "framework": "vite",
      "outputDir": "dist",
      "deployPath": "/web"
    }
  ],
  "gateway": {
    "routes": [
      { "path": "/api", "target": "function:pay-common" },
      { "path": "/web", "target": "hosting:web" }
    ]
  }
}

Corresponding project structure:

project/
├── cloudbaserc.json
├── functions/
│   └── pay-common/
│       └── index.js
└── web/
    └── dist/        # build output (generated by tcb app build)

Directory Convention

See Project Directory Convention below for the full layout. Database migrations default to cloudbase/migrations/.

Deployment Flow

Overwrite Confirmation

• Functions that already exist in the cloud (update scenario) are confirmed before overwriting
• --yes proceeds directly; interactive mode confirms item by item
• When no confirmation mechanism is provided, it conservatively skips (never overwrites production without consent)

Command Options

--dry-run

Outputs only the change plan (terraform plan mindset), without deploying:

tcb deploy --dry-run

Shows field-level changes (from → to) and database migration plans.

--only / --skip

Deploy only specified types / skip specified types:

tcb deploy --only=functions          # deploy cloud functions only
tcb deploy --only=hosting,gateway    # deploy hosting and gateway only
tcb deploy --skip=gateway            # skip gateway

Available types: database / functions / app / hosting / gateway.

--mode / --env-id

Apply environment-specific configuration:

tcb deploy --mode=production       # apply envOverrides.production + .env.production
tcb deploy --env-id=xxx            # specify environment (highest priority)

--yes

Proceed with function overwrite updates directly (CI / AI Agent scenarios):

tcb deploy --yes

Concurrency (--concurrency)

Default 1 (strictly serial), consistent with historical behavior. When set, multiple resource instances of the same type are deployed in parallel; cross-type resources still follow the dependency order (database → functions → app → hosting → gateway) serially, without breaking dependencies.

tcb deploy --concurrency 3          # parallelize across functions/hosting sites, max 3 at a time

• Applies only to "consecutive instances of the same type" (e.g., multiple hosting sites, multiple functions); functions vs hosting, hosting vs gateway always run serially.
• Concurrency is capped at 20 to avoid excessive pressure on backend APIs.

Failure Interruption (--continue-on-error)

Default is fail-fast: if any resource fails to deploy, subsequent resources are interrupted and the process exits with a non-zero exit code (for CI/CD awareness). To "run through everything and view the failure count at the end", add --continue-on-error:

tcb deploy --continue-on-error      # continue deploying the rest even if one resource fails

Exception: database failures always force interruption (regardless of --continue-on-error), because subsequent resources may depend on the newly created database schema.

Resource Configuration Overview

See the corresponding docs for full field details:

Resource	Config field	Key notes	Docs
Database migrations	database	postgresql only; migration files 14-digit-timestamp_name.sql, default dir cloudbase/migrations/; conflicts abort deployment	PostgreSQL Management
Cloud functions	functions	Event / HTTP types; zip code or image deployment (buildStrategy); HTTP functions support public anonymous access and gatewayPath gateway routing	Function Configs · Deploying Functions
Cloud app	app	Build path decided by framework: static direct upload / others cloud build	Application Deployment
Static hosting	hosting	Array of multiple sites; run tcb app build locally first, then tcb deploy only uploads output	Static Website Hosting · tcb app build
Gateway routes	gateway.routes	target: function:<name> / hosting:<name>; pathRewrite auto-generated	Configuration File - Gateway
Environment overrides	envOverrides	Merged by --mode	Config File

Function target type

The gateway route target: function:<name> supports two function types:

• HTTP type (type: "HTTP") → created as a WEB_SCF route
• Event type (regular function) → created as an SCF route (verified to work; the gateway wraps the HTTP request as an event and forwards it to the function)

The CLI automatically queries function details to determine the type; both types can serve as gateway targets.

Database Migration (database)

Declarative deployment supports the database resource, applying PostgreSQL migrations in order according to the SQL files under the database.migrations directory:

Dimension	Description
Supported types	Only type: postgresql (type: nosql is passed through without orchestration)
Migration files	Named 14-digit-timestamp_lowercase-name.sql (e.g. 20260101120000_init.sql), default dir cloudbase/migrations/
Plan (--dry-run)	Aggregated into a single change item: pending → create
Conflict handling	Target database already has a migration with the same name → abort deployment
Failure policy	database failure always forces interruption (even with --continue-on-error), since subsequent resources may depend on the new schema

Database migration failure aborts the entire deployment

database is ordered first in orchestration (database → functions → app → hosting → gateway); once it fails, subsequent resources are not executed. Run tcb deploy --dry-run first to confirm the migration plan is correct.

Project Directory Convention

Recommended layout (using vibe-app as an example):

vibe-app/
├── cloudbaserc.json          # declarative config (core contract, envId/version 2.1)
├── .env                      # secrets (not in Git; reads .env.<mode> when --mode <mode>)
├── .env.example              # secrets template (in Git)
├── cloudbase/migrations/               # database migrations (SQL, default dir)
│   ├── 20260101120000_init.sql
│   └── 20260102150000_add_users.sql
├── functions/                # cloud function code (functionRoot defaults to ./functions)
│   ├── task-runner/          # Event function: exports.main(event, context)
│   └── api-server/           # HTTP function: requires scf_bootstrap
├── web/                      # frontend code (pointed by hosting[].root)
└── Dockerfile                # optional, for image deployment (inside function dir)

Path resolution rules:

Resource	Config field	Default / resolution
Database migration dir	database.migrations	cloudbase/migrations/ (relative to project root)
Function root	functionRoot	functions/
Function code dir	dir / functionRoot+name	Explicit dir → {cwd}/{dir} (independent of functionRoot); otherwise {cwd}/{functionRoot}/{name}
Frontend site	hosting[].root	Directory relative to cloudbaserc

FAQ

1. gateway.routes validation failure (should NOT have additional properties)

Schema v2.1 does not allow extra fields. For example, cdnType is not a valid route field — remove it; use accessType (DIRECT / CDN / CUSTOM / EO) to control CDN access:

{ "path": "/web", "target": "hosting:web", "accessType": "DIRECT" }

2. HTTP function dependency installation rules

Function type	Runtime	Dependency installation
Event	Any	Cloud-side install (default)
HTTP	Node.js	Cloud-side install (default)
HTTP	Non-Node.js (Python/Php/Java/Go)	Must install locally and upload with the code

For HTTP non-Node.js functions, ensure dependencies are installed locally (e.g., Python pip install into the function directory).

3. Will existing functions be overwritten?

Functions that already exist (update scenario) require confirmation by default; --yes proceeds. Declarative deployment semantics align with tcb fn deploy --force.

4. Domain-level fields do not take effect on already-bound domains

certId / protocol / accessType are domain-level fields (shared by all routes under the same domain). When creating routes on an already-existing domain, these fields do not override the domain's original values (e.g. if the domain is already bound with HTTP_AND_HTTPS, setting protocol: "HTTPS" has no effect) — this is the platform's safety behavior to avoid affecting other business routes under the same domain. They only take effect when the domain is first created.

5. Gateway route idempotency semantics

tcb deploy gateway routes converge idempotently (create / update / skip):

• Route does not exist → create (create)
• Route exists and the explicitly declared fields match → skip (skip)
• Route exists but explicitly declared fields differ → update (update, calls modifyHttpServiceRoute)

Only explicitly declared fields are compared (enableAuth / enablePathTransmission are compared only when explicitly configured; qpsPolicy / pathRewrite are compared only when the local value is present), and undeclared fields do not override the cloud configuration. Duplicate paths are not treated as errors (unlike the INVALID_PARAM of imperative tcb routes add). See Configuration File - Gateway for the authoritative field definitions.

References

• Pre-deploy Validation (tcb validate)
• Config File
• HTTP Routes
• Function Configs