Skip to content

cloud-deployment.mdx

Latest commit

 

History

History
144 lines (107 loc) · 4.92 KB

cloud-deployment.mdx

File metadata and controls

144 lines (107 loc) · 4.92 KB
Raw
title Deployment Modes
description Choose between local standalone runtime and Cloud-managed environment deployment.

Deployment Modes

This repository ships the framework runtime, examples, adapters, CLI, docs, and the published console bundle. Local development is a single-environment runtime. Cloud deployment uses a separate ObjectStack Cloud control plane plus the environment-aware runtime seams exported from @objectstack/runtime.

Mode Runs from this repo Environment selection Typical use
Local example Yes One active OS_ENVIRONMENT_ID Framework development and smoke tests
Standalone app Yes One compiled artifact or stack config Self-hosted app backend
Cloud-managed environment Runtime seams only Cloud control plane, hostname, scoped URL, header, or session SaaS and multi-environment deployments

Local runtime

Use the repo scripts for framework development:

PORT=3000 pnpm dev
pnpm dev:crm -- --fresh -p 38421
pnpm docs:dev

pnpm dev starts the showcase kitchen-sink example. It is the best local exercise path for objects, views, flows, AI metadata, security, and the console bundle.

For a generated app:

os dev
os start
os serve --artifact ./dist/objectstack.json

The active environment is selected with OS_ENVIRONMENT_ID.

Standalone artifact runtime

Any directory with a compiled dist/objectstack.json can boot through the CLI or @objectstack/runtime helpers:

os compile
OS_ENVIRONMENT_ID=env_prod os serve --artifact ./dist/objectstack.json

Deployment config stays outside the artifact. Database URLs, auth secrets, runtime credentials, and environment identity are injected through process env or the host's deployment config.

Cloud-managed deployment

Publishing and installing are separate steps. The CLI publishes a versioned package to your organization's catalog — it does not touch any environment, and you never pass an environment id:

os cloud login        # once: stores a cloud token
os package publish     # → sys_package + immutable, checksummed sys_package_version

See the cloud package and package-version references.

Installing then happens inside the target environment: sign in to that environment's Console → Marketplace → pick the package → Install. The install is authorized by your environment login and applied to that environment (metadata + sample data); the kernel is evicted so it is live on the next request — no restart, and no environment id to remember.

CI shortcut. A pipeline deploying to a known environment can publish and install in one call: os package publish --env <id> --install. This is for automation only — interactive installs happen in the environment Marketplace.

Legacy env-revision path. os publish posts compiled metadata straight to an environment as a revision, rather than as a versioned package:

OS_CLOUD_URL=https://cloud.example.com OS_ENVIRONMENT_ID=env_prod os publish
# POST /api/v1/cloud/environments/:environment/metadata
# rollback: POST /api/v1/cloud/environments/:environment/revisions/:commit/activate

It still works, but the package flow above is the direction of travel (ADR-0006 v4): sys_environment_revision is retired once all publishes go through the package endpoints.

Cloud control-plane hosts, database provisioning, billing, and public SaaS deployment are outside this framework repository. The framework runtime exposes the environment registry, marketplace proxy, and runtime-config seams consumed by that distribution.

Routing precedence

Environment-aware hosts resolve requests in this order:

  1. /api/v1/environments/:environmentId/...
  2. Hostname through the environment registry
  3. X-Environment-Id
  4. session.activeEnvironmentId
  5. Configured default environment
  6. Single unambiguous environment

Control-plane paths under /api/v1/cloud/environments/... are not data-plane requests and do not run through a target environment kernel.

Environment variables

Variable Purpose
OS_ENVIRONMENT_ID Active local or publish target environment.
OS_CLOUD_URL Cloud control-plane base URL used by publish/package commands.
OS_ARTIFACT_PATH Artifact path for os serve and standalone hosts.
OS_DATABASE_URL Local runtime business database URL.
OS_DATABASE_DRIVER Local runtime driver id.
AUTH_SECRET Better Auth session secret for hosted runtimes.
PORT / HOST HTTP bind settings.

Third-party provider variables such as OPENAI_API_KEY, TURSO_*, SMTP_*, RESEND_API_KEY, and OAuth client secrets keep their provider names.

Related