Supported Regions:上海

Deploying Static Applications to a Private Environment with CloudBase CLI

This document guides you through deploying a front-end static application (React / Vue / Vite, etc.) to a WeDa private deployment environment using CloudBase CLI.

Prerequisites

Requirements

WeDa environment: private deployment completed, with the environment ID and platform address at hand
Credentials: console account and password of the private deployment environment
CLI: @cloudbase/cli 3.8.7 or later (this capability is available from 3.8.7; check with tcb -v)
Local environment: Node.js installed, and the project builds locally

Step 1: Configure cloudbaserc.json

Add the private environment configuration to cloudbaserc.json in your project root:

{
  "envId": "software-xxxxxxxxxxxx",
  "privateSettings": {
    "credential": {
      "weda": {
        "username": "admin",
        "password": "******"
      }
    },
    "endpoints": {
      "cliApi": "http://your-private-domain.com"
    }
  },
  "app": {
    "serviceName": "my-app",
    "framework": "vite",
    "outputDir": "dist"
  }
}

Fields:

Field	Required	Description
`envId`	Yes	Private environment ID
`privateSettings.credential.weda.username` / `password`	Yes	Console account of the private environment; the only usable credential in this deployment mode
`privateSettings.endpoints.cliApi`	Yes	Private platform address, including the protocol (e.g. `http://1.2.3.4`)
`privateSettings.privateUin`	No	User uin of the private environment
`app.serviceName`	No	Application name; determines the access URL sub-path and the version name prefix (e.g. `my-app-003`). Defaults to the positional argument → interactive selection → project directory name
`app.outputDir`	Yes	Build output directory; a key setting for private deployment, see Step 2
`app.deployPath`	No	Access sub-path, default `/<app.serviceName>`; changing it changes the access URL
`app.ignore`	No	Extra ignore rules; must be configured explicitly in a private environment, see Notes
`app.envVariables`	No	Has no effect in a private environment: not injected into the local build; set them yourself when building locally (e.g. `.env`)

No login required

When privateSettings is present, the CLI automatically detects the private environment and handles authentication. Running tcb login is not required, and no object storage keys are needed.

Step 2: Build locally

Important: no cloud build in private environments

For public cloud deployment, the server performs "install dependencies → build". A private environment does not provide cloud build capabilities, so you must build the output directory locally first.

If the output directory does not exist, the deployment command fails immediately and prompts you to build locally first.

npm install
npm run build

After the build, make sure the app.outputDir directory (default: dist) has been generated.

Step 3: Deploy

tcb app deploy

Common options (run tcb app deploy -h for the full list):

Option	Description	Effective in a private environment
`[serviceName]`	Positional argument, application name; defaults to `app.serviceName` → interactive selection → project directory name	Yes
`-e, --env-id <envId>`	Override the environment ID (`--envId` is a deprecated alias)	Yes
`--output-dir <dir>`	Override `app.outputDir`; decides which directory is uploaded	Yes
`--deploy-path <path>`	Override `app.deployPath`	Yes
`--cwd <path>`	Project directory, relative path (defaults to the current directory)	Yes
`--ignore <patterns>`	Ignore patterns, comma-separated, appended after `app.ignore`	Yes
`--enable-git-ignore`	Merge the project `.gitignore` rules (off by default)	Yes
`-f, --force`	Skip the confirmation when the application name already exists (recommended for CI)	Yes
`--framework <fw>`	Framework type, recorded with the version (`static` is treated as `other`)	Recorded only
`--install-command` / `--build-command`	Install / build command	No, see Step 2

The CLI performs the following in sequence: package the output directory → upload → create the cloud application → poll the build status.

Step 4: Access the application

After a successful deployment, the terminal prints the access URL and version:

Deployment succeeded!
  Access URL: http://your-private-domain.com/my-app/
  Version: my-app-003
  Duration: 32s

Note

The application access URL looks like http://<domain>/<serviceName>; whether a trailing slash is present depends on the domain returned by the platform — always trust the URL printed in the terminal. If a fallback address is printed, use the application domain shown in the platform console instead.

Querying and deleting applications

Application management commands are also available in a private environment:

Command	Description
`tcb app list`	List applications in the environment
`tcb app info <serviceName>`	Show details of an application
`tcb app versions list <serviceName>`	List the version history of an application
`tcb app versions detail <serviceName>`	Show details of a version (latest by default)
`tcb app delete <serviceName>`	Delete an application and all of its versions (supports `--dry-run`)

tcb app list
tcb app info my-app
tcb app versions list my-app
tcb app versions detail my-app

# Preview before deleting
tcb app delete my-app --dry-run

Note

Access URLs are rendered with the platform protocol (http://<domain>/<serviceName>)
app versions detail resolves the latest version automatically when --version-name is omitted
app delete removes all versions of the application and cannot be undone; use --dry-run first to confirm the target

About tcb app build

tcb app build is not provided in a private environment.

It builds static hosting projects declared in cloudbaserc.json (hosting[]), and its artifacts are consumed by tcb deploy / tcb hosting deploy — neither of which works in a private environment, since the platform has no static hosting service; the artifacts would have nowhere to go. It also handles only hosting[], not the app field used in this guide.

Use your project's own build command (e.g. npm run build) to produce app.outputDir instead.

Differences from public cloud deployment

Dimension	Public cloud	Private (software)
Build location	Cloud (server-side)	Local; build the output first
Uploaded content	Project source code	Contents of the `app.outputDir` directory
`app.installCommand` / `app.buildCommand`	Sent to the server to execute	Ignored, with a notice printed
`app.framework: "static"`	Uses the static hosting direct-upload path	Treated as `other`
Access URL format	`https://{envId}-{appId}.tcloudbaseapp.com`	`http://<domain>/<serviceName>` (trust the URL printed in the terminal)
Authentication	`tcb login`	Account and password from the configuration file

Build output is uploaded, not source

A private environment publishes the root of the uploaded package as the site content. The CLI locates the upload directory automatically based on app.outputDir, so be sure to build locally first and configure outputDir correctly.

Notes

Available commands: in a private environment the CLI registers only supported commands; run tcb -h to see the current list
No SPA route fallback: requests to extension-less paths return NoSuchKey instead of falling back to index.html; when using React Router and similar, prefer hash mode
Static hosting only: private environments support only the static-hosting deployment type, which the CLI always uses
No cloud build log link: private environments have no corresponding console page, so no link is printed
Configure app.ignore explicitly: the app deploy path does not exclude node_modules by default. When outputDir points to the project root (.), you must configure it yourself, otherwise dependencies are packed and published (bare directory names are expanded to <dir>/** automatically, so node_modules is enough). .git and .DS_Store are always excluded by the CLI — no need to list them

FAQ

Symptom	Cause and resolution
"not a valid command"	The command is not supported in a private environment; run `tcb -h` to see available commands
Missing private credential	`privateSettings.credential.weda` is not configured; configuring only `secretId` / `secretKey` does not work in this mode
Missing platform address	`privateSettings.endpoints.cliApi` is not configured
"build and produce dist locally first"	The output directory does not exist; run `npm run build` first
Site opens but static assets return 404	The source directory was uploaded instead of the output directory; check `app.outputDir`
Error "`app.outputDir` resolves outside the project directory"	`outputDir` is a `../` path or an absolute path; the upload directory must stay inside the project — use a relative path such as `dist`
Error "`app.outputDir` escapes the project directory via a symbolic link"	The `outputDir` directory is a symlink whose real path is outside the project; remove the symlink, or copy the external content into the project during the build
Deployment failed	The error message includes a request ID that you can provide to the platform team

Prerequisites​

Step 1: Configure cloudbaserc.json​

Step 2: Build locally​

Step 3: Deploy​

Step 4: Access the application​

Querying and deleting applications​

Differences from public cloud deployment​

Notes​

FAQ​