Full-Stack Deployment
Replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment before running the examples.
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:
Mode A: browser → Sites → the Client SDK only calls Functions → TablesDB (the frontend never connects directly to the data plane).
Mode B: reads connect directly to TablesDB/Storage/Realtime, while sensitive writes go through
functions.createExecution(e.g., a kanban demo).Mode C: Sites SSR——the SSR side uses an API Key to read the database, and the user Session uses the Client SDK to connect directly from the browser to
/v1(note the Cookie non-passthrough limitation in sites.md).
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)
Division of the two keys: the Console login session performs Console-only operations (creating projects, creating Teams,
projects.createPlatformregistering platforms, organization queries); the project API Key performs resource operations (databases/tables/storage/functions/sites/deployments).platforms.read/writeis not among the grantable scopes of a project Key——calling createPlatform with a project Key fails directly.Sign in to the target Console and confirm the project before Console-only operations; verify session propagation and redirect behavior before automating them.
Credentials are read only from the project's
.env(priority: project-root.env>scripts/.env> process environment); it is forbidden to log passwords/Keys/JWTs, and forbidden to commit deployment scripts into the user's repository.API Key scope recommendations (17 items): databases / tables / columns / indexes / rows / buckets / functions / execution / sites each read+write, plus
rules.read. ConsolecreateKeyscopes are lowercase dot-separated strings (e.g.,sites.write).2.6.0 security defaults: Function/Site install, build, and start commands run under a restricted identity and fail directly when conditions are unmet, with no fallback to higher privilege; Function API Keys are no longer accepted via query string——use a protected header or platform-injected runtime authentication.
Usage workflow
Data layer:
tablesDB.create({ databaseId, name })→tablesDB.createTable({ databaseId, tableId, name, rowSecurity, columns, indexes })(columns/indexes inline, except relationship columns) → create buckets (storage.createBucket).Function layer:
functions.create(...)→ configureexecute(who can invoke) andscopes(runtime dynamic Key permissions; different from execute) →functions.createVariable(variablevariableIdrequired) → package as tar.gz (excludingnode_modules, build artifacts,.env) →functions.createDeployment({ functionId, code, activate: true })→ poll deploymentready.Frontend layer:
sites.create(...)(framework/adapter/build command, see sites.md) →sites.createVariable(VITE_*non-secret variables +secret: trueserver-side Key) → package and uploadsites.createDeployment({ siteId, code, activate: true })(HTTP 202) → pollgetDeploymentuntilready.Platform registration: under the Console Session,
projects.createPlatform({ projectId, type: 'web', name, hostname })——hostname withouthttps://; register localhost,127.0.0.1, and Sites domains; unregistered domains allow pages to open but APIs report CORS/Invalid URI.Resolve URL: use the current deploymentId with the Console SDK's
proxy.listRulesmatching rules to get the site URL (rules[0]is forbidden / do not reuse old URLs); query the function execution context on the spot.Report back: Project ID, Function ID, Site URL, deploymentId, Console URL (
{consoleOrigin}/console/project-{region}-{projectId}/overview/platforms, origin = endpoint minus/v1, region usuallydefault).
Key parameters and returns
Synchronous Functions have a limit of about 30 seconds through the load balancer (timeout reports 408): for long tasks, switch to
async: true+getExecutionpolling.Function runtime-injected variables:
APPWRITE_FUNCTION_API_ENDPOINT,APPWRITE_FUNCTION_PROJECT_ID, and request headersx-appwrite-key/x-appwrite-user-id——do not create variables with the same names yourself.Idempotency conventions: Site/Function use fixed IDs (get first, then update/create); variables upsert by key; deployments use
ID.unique()each time; Platforms are deduplicated by hostname.For build timeouts, evaluate based on 900 seconds; the deployment polling example uses 5-second intervals with an upper bound of 10 minutes.
Errors and boundaries
Sites capability whitelist not allowed → pass the gate in sites.md first before continuing; stop on failure (you may keep a checkpoint: write the Team/Project/Key back to
.env, fix, and rerun).Environment consistency: the endpoint must be in the same environment as the account's Console (SIT
https://appbuild-sit.oceanbase.com/v1, productionhttps://appbuild.oceanbase.com/v1); ask when no configuration exists rather than defaulting to SIT.Changed Site variables only take effect after re-running createDeployment; frontend
VITE_*endpoints must include/v1.After modifying variables or rolling back a deployment, URLs still follow "the rules bound to the current deploymentId".
SDK Category Differences
Server SDK (server-sdk/nodejs.md): the full set of tablesDB / storage / functions / sites resource operations——the workhorse of deployment scripts.
Console SDK (console-sdk/nodejs.md): Console-only operations such as projects/teams/Keys/platform registration.
Client SDK (client-sdk/web.md): does not participate in deployment; only accesses the
/v1data plane of deployed applications.For combined usage of the two, see server-sdk/nodejs.md "Using Together with the Console SDK".
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.
The Node.js examples use SDK 2.12 and first disable redirects for the requests on this page that pass through prepareRequest; this does not protect every SDK request method. Revalidate credential and redirect behavior when changing SDK versions or calling other methods.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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
// SDK 2.12: reject redirects for the request paths used in this guide.
const originalPrepareRequest = client.prepareRequest;
if (typeof originalPrepareRequest !== 'function') throw new Error('Redirect control unavailable');
client.prepareRequest = function (...args) {
const request = originalPrepareRequest.apply(this, args);
request.options.redirect = 'error';
return request;
};
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 });Java SDK 2.12 default requests may forward the project Key across host redirects. Until a safe configuration is verified, executable resource operations are omitted. Use the REST steps in this section; see Java Server SDK for installation.
Python SDK 2.12 default requests may carry the project Key across host redirects; a safe configuration has not been verified, so executable writes are omitted. Use the REST steps below; see Python Server SDK for installation and client details.
Create the table only after the database succeeds; create the bucket separately and check each error. Verify Go SDK redirect configuration for the target environment, or use the REST steps below; see Go Server SDK for installation.
Set APPBASE_ENDPOINT to the target API address including /v1; configure APPBASE_PROJECT_ID and APPBASE_API_KEY on a controlled backend. Run one step at a time and continue only after HTTP 2xx; keep the key out of logs and command arguments.
Create the database, then create the table after success.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/tablesdb" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"databaseId": "app-db", "name": "App", "enabled": true}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)Create the table.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/tablesdb/app-db/tables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"tableId": "tasks",
"name": "Tasks",
"rowSecurity": true,
"columns": [{"key": "title", "type": "string", "size": 256, "required": true}],
"indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]
}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)Create the bucket separately if needed.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/storage/buckets" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"bucketId": "attachments", "name": "附件", "fileSecurity": true, "enabled": true}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)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.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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 --exclude=.git --exclude='.env*' --exclude=.npmrc -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'Java SDK 2.12 default requests may forward the project Key across host redirects. Until a safe configuration is verified, executable resource operations are omitted. Use the REST steps in this section; see Java Server SDK for installation.
The Python Server SDK 2.12.0 default transport may forward the project API key on redirects. Use the REST tab in this section.
functions := agentbase.NewFunctions(cl)
// Isomorphic method names (PascalCase): Create / CreateVariable / CreateDeployment /
// GetDeployment (poll until Status=ready); optional parameters use functions.With… options,
// Refer to the module source codeSet APPBASE_ENDPOINT to the target API address including /v1; configure APPBASE_PROJECT_ID and APPBASE_API_KEY on a controlled backend. Run one step at a time and continue only after HTTP 2xx; keep the key out of logs and command arguments.
Create the function and confirm success.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"functionId": "send-mailer",
"name": "Send Mailer",
"runtime": "node-22",
"execute": ["users"],
"scopes": ["databases.read", "tables.read", "rows.read", "databases.write", "tables.write", "rows.write"],
"entrypoint": "src/main.js",
"commands": "npm install"
}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)Configure the function variable and confirm success.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions/send-mailer/variables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_database_id", "key": "DATABASE_ID", "value": "app-db"}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)Run the following packaging command from the project directory, then upload.
tar -czf code.tar.gz --exclude=node_modules --exclude=.git --exclude='.env*' --exclude=.npmrc -C functions/send-mailer .Upload the archive; after
202, poll until the deployment isready.
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions/send-mailer/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-F "code=@./code.tar.gz" \
-F "activate=true")"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)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.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
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: '<APPBASE_ENDPOINT_WITH_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'Java SDK 2.12 default requests may forward the project Key across host redirects. Until a safe configuration is verified, executable resource operations are omitted. Use the REST steps in this section; see Java Server SDK for installation.
The Python Server SDK 2.12.0 default transport may forward the project API key on redirects. Use the REST tab in this section.
sites := agentbase.NewSites(cl)
// Isomorphic method names (PascalCase): Create / CreateVariable / CreateDeployment /
// GetDeployment (poll until Status=ready); optional parameters use sites.With… options,
// Refer to the module source codeStep 1: Create the site; confirm HTTP 2xx and inspect the result.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"siteId": "portal",
"name": "用户门户",
"framework": "react",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html",
"outputDirectory": "dist",
"installCommand": "npm install",
"buildCommand": "npm run build"
}'
)Step 2: Set the variable separately after site creation succeeds; confirm HTTP 2xx.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites/portal/variables" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_endpoint", "key": "VITE_APPWRITE_ENDPOINT", "value": "<APPBASE_ENDPOINT_WITH_V1>"}'
)Step 3: Submit the deployment separately after the variable is set.
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites/portal/deployments" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-F "code=@./site.tar.gz" \
-F "activate=true"
)After a 202 response, poll GET /v1/sites/portal/deployments/{deploymentId} using the returned deployment ID until the status is ready.
Platform registration (Console only)
Sign in to the target Console and open the project’s Overview → Integrations → Platforms to add the Web hostnames actually in use. A project API Key does not grant platforms.*; enter a hostname without a protocol. See project overview.
Verification and reporting: confirm the deployment URL
In the Console, inspect the domain rule for this deploymentId, verify that its status is verified, and visit the address. API consumers must page through rules for the current deployment; if no verified match exists, stop and inspect domain configuration rather than reusing an old URL or redeploying. Report the Project ID, Function ID, Site URL, and current deploymentId. See site management.
Example Guide
JavaScript (Node deployment sequence + Console platform registration): examples/javascript.md
Java:examples/java.md