Docs
Contents

Full-Stack Deployment

Overview and use cases

Deploy a complete application (TablesDB data model + Storage resources + Function backend + Sites frontend) to a project from scratch: create database and tables → deploy functions → deploy the site → register platforms → output accessible URLs. Suited to agent-automated delivery, scaffolding initialization, and CI-driven full-stack releases.

Three typical architectures:

Basis: Sites/Functions/TablesDB service-plane coverage is complete in v2.7.0 SDK source, and the security defaults (restricted identity, Function API Key not via query string) take effect from 2.6.0——this page is written for the full workflow.

Prerequisites (credential gates)

Usage workflow

  1. Data layer: tablesDB.create({ databaseId, name }) → tablesDB.createTable({ databaseId, tableId, name, rowSecurity, columns, indexes }) (columns/indexes inline, except relationship columns) → create buckets (storage.createBucket).

  2. Function layer: functions.create(...) → configure execute (who can invoke) and scopes (runtime dynamic Key permissions; different from execute) → functions.createVariable (variable variableId required) → package as tar.gz (excluding node_modules, build artifacts, .env) → functions.createDeployment({ functionId, code, activate: true }) → poll deployment ready.

  3. Frontend layer: sites.create(...) (framework/adapter/build command, see sites.md) → sites.createVariable (VITE_* non-secret variables + secret: true server-side Key) → package and upload sites.createDeployment({ siteId, code, activate: true }) (HTTP 202) → poll getDeployment until ready.

  4. Platform registration: under the Console Session, projects.createPlatform({ projectId, type: 'web', name, hostname })——hostname without https://; register localhost, 127.0.0.1, and Sites domains; unregistered domains allow pages to open but APIs report CORS/Invalid URI.

  5. Resolve URL: use the current deploymentId with the Console SDK's proxy.listRules matching rules to get the site URL (rules[0] is forbidden / do not reuse old URLs); query the function execution context on the spot.

  6. Report back: Project ID, Function ID, Site URL, deploymentId, Console URL ({consoleOrigin}/console/project-{region}-{projectId}/overview/platforms, origin = endpoint minus /v1, region usually default).

Key parameters and returns

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Data layer: create database, tables, and buckets

Credentials: project API Key (databases.* / tables.* / columns.* / indexes.* / buckets.*). Lists/indexes are submitted inline within createTable (relationship columns go through a dedicated endpoint); the Web SDK is not involved in deployment, so there is no Web tab.

import { Client, TablesDB, Storage } from 'agentbase-node-sdk';

const client = new Client()
  .setEndpoint(process.env.APPBASE_ENDPOINT)     // Includes /v1, same environment as the account Console
  .setProject(process.env.APPWRITE_PROJECT_ID)
  .setKey(process.env.APPWRITE_API_KEY);         // Project API Key

const tablesDB = new TablesDB(client);
await tablesDB.create({ databaseId: 'app-db', name: 'App' });
await tablesDB.createTable({
  databaseId: 'app-db',
  tableId: 'tasks',
  name: 'Tasks',
  rowSecurity: true,
  columns: [/* Column definitions inline; except relationship columns */],
  indexes: [],
});

const storage = new Storage(client);
await storage.createBucket({ bucketId: 'attachments', name: '附件', fileSecurity: true });

Functions layer: create, configure, and deploy functions

Credentials: project API Key. execute governs who may invoke, scopes governs permissions for dynamic keys in the function runtime — the two are different things; variables require a new createDeployment to take effect for subsequent executions.

import { Functions, ID } from 'agentbase-node-sdk';
import { InputFile } from 'agentbase-node-sdk/file';
const functions = new Functions(client);

await functions.create({
  functionId: 'send-mailer',
  name: 'Send Mailer',
  runtime: 'node-22',
  execute: ['users'],                 // Who can call it
  scopes: ['databases.read', 'tables.read', 'rows.read',
           'databases.write', 'tables.write', 'rows.write'],
  entrypoint: 'src/main.js',
  commands: 'npm install',
});
await functions.createVariable({
  functionId: 'send-mailer',
  variableId: ID.unique(),
  key: 'DATABASE_ID',
  value: 'app-db',
});

// tar -czf code.tar.gz --exclude=node_modules -C functions/send-mailer .
const dep = await functions.createDeployment({
  functionId: 'send-mailer',
  code: InputFile.fromPath('./code.tar.gz'),
  activate: true,
});
// Poll getDeployment (functionId + dep.$id) until status === 'ready'

Frontend layer: create a site, inject variables, and deploy

Credentials: project API Key (sites.*). Non-secret VITE_* variables add a secret: true server-side Key; VITE_APPWRITE_ENDPOINT must include /v1; changing variables requires redeployment. For framework and adapter details, see sites.mdx.

import { Sites, ID } from 'agentbase-node-sdk';
import { InputFile } from 'agentbase-node-sdk/file';
const sites = new Sites(client);

await sites.create({
  siteId: 'portal',
  name: '用户门户',
  framework: 'react',            // Full list at GET /sites/frameworks
  buildRuntime: 'node-22',
  adapter: 'static',
  fallbackFile: 'index.html',    // Required for SPA
  outputDirectory: 'dist',
  installCommand: 'npm install',
  buildCommand: 'npm run build',
});
await sites.createVariable({
  siteId: 'portal',
  variableId: ID.unique(),
  key: 'VITE_APPWRITE_ENDPOINT',
  value: 'https://appbuild.oceanbase.com/v1',
});

// Package frontend source (exclude node_modules and local build artifacts; build runs remotely via npm run build)
const dep = await sites.createDeployment({
  siteId: 'portal',
  code: InputFile.fromPath('./site.tar.gz'),
  activate: true,                // HTTP 202
});
// Poll sites.getDeployment (siteId + dep.$id) until status === 'ready'

Platform registration (Console only)

Credentials: Console Session (email/password login + setCookie) — the project API Key has no platforms.* scope, and calling createPlatform fails directly. The hostname carries no https://; the REST management endpoints are not exposed in the apis documentation, so there is no REST tab.

import { Client, Account, Projects, PlatformType } from 'agentbase-console-sdk';

const client = new Client()
  .setEndpoint(process.env.APPBASE_ENDPOINT)   // Includes /v1
  .setProject(process.env.APPBASE_CONSOLE_PROJECT_ID || 'console');  // Console context

// createEmailPasswordSession alone is not enough: after intercepting the login response set-cookie and concatenating it
// client.setCookie(sessionCookie); otherwise subsequent calls are rejected as a guest
const account = new Account(client);
await account.createEmailPasswordSession({
  email: process.env.APPBASE_EMAIL,
  password: process.env.APPBASE_PASSWORD,
});

const projects = new Projects(client);
const list = await projects.listPlatforms({ projectId });   // projectId is the application project ID
const registered = new Set(
  list.platforms.filter((p) => p.type === 'web').map((p) => p.hostname),
);

for (const hostname of ['localhost', '127.0.0.1', '<sites-preview-hostname>']) {
  if (!registered.has(hostname)) {
    await projects.createPlatform({
      projectId,                 // App project ID
      type: PlatformType.Web,
      name: hostname,
      hostname,                  // Without https://
    });
  }
}

Verification and reporting: resolve the deployment URL

Credentials: project API Key (requires rules.read) to call proxy.listRules; the Console SDK likewise exports Proxy (loaded from the Console Session). The REST endpoints for rules are not exposed in the apis documentation, so there is no REST tab. Report the Project ID, Function ID, Site URL, deploymentId, and Console URL ({consoleOrigin}/console/project-{region}-{projectId}/overview/platforms, origin = endpoint with /v1 removed, region is usually default).

import { Proxy, Query } from 'agentbase-node-sdk';

const proxy = new Proxy(client);   // Project API Key (rules.read)

const rules = await proxy.listRules({
  queries: [
    Query.equal('deploymentResourceId', [siteId]),
    Query.equal('deploymentResourceType', ['site']),
  ],
});
const withDomain = rules.rules.filter((r) => r.domain);
// Only rules bound to this deploymentId are recognized; order does not guarantee the latest; do not fetch rules[0]
const bound = withDomain.find((r) => r.deploymentId === deploymentId);
const siteUrl = `https://${bound.domain}`;

Example Guide