Skip to content

Commit 2a87ef1

Browse files
hotlongCopilot
hotlong
and
Copilot
committed
docs: add deployment guide and runtime smoke path
- document getting started, install, configure, upgrade and architecture pages - make Docker Compose default to a mounted artifact path and persistent volumes - add Docker image healthcheck and runtime directories - add runtime smoke script for local validation - include driver dependencies needed by runtime package dynamic imports Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 99e052d commit 2a87ef1

15 files changed

Lines changed: 438 additions & 14 deletions

File tree

‎.env.example‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# ObjectOS runtime
2+
#
3+
# Copy to `.env` for local docker-compose usage:
4+
#
5+
# cp .env.example .env
6+
# docker compose -f docker/docker-compose.yml up --build
7+
8+
# Host port published by docker-compose.
9+
OBJECTOS_PORT=3000
10+
11+
# Cloud-connected mode:
12+
# OS_CLOUD_URL=https://cloud.objectstack.ai
13+
# OS_PROJECT_ID=proj_xxxxxxxxxxxxx
14+
# OS_CLOUD_API_KEY=
15+
16+
# Offline / air-gapped mode:
17+
# Keep this default when using docker-compose. Put the compiled artifact at:
18+
# docker/artifacts/objectstack.json
19+
OS_ARTIFACT_FILE=/artifacts/objectstack.json
20+
OS_PROJECT_ID=proj_local
21+
22+
# Per-project business data. In docker-compose this is persisted on the
23+
# `objectos-data` volume.
24+
OS_BUSINESS_DB_URL=file:/var/lib/objectos/data.db

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,5 @@ coverage/
1414
.vercel
1515
*.db
1616
*.db-journal
17+
docker/artifacts/*
18+
!docker/artifacts/.gitkeep

‎README.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,12 @@ See [`apps/objectos/objectstack.config.ts`](apps/objectos/objectstack.config.ts)
6060
```bash
6161
pnpm install
6262

63-
# Boot the runtime against a local compiled artifact
64-
OS_ARTIFACT_FILE=./dist/objectstack.json pnpm objectos:dev
63+
# Build the runtime distribution and docs
64+
pnpm build
65+
66+
# Boot the runtime against a local compiled artifact produced by apps/objectos
67+
cd apps/objectos
68+
OS_ARTIFACT_FILE=dist/objectstack.json PORT=3200 pnpm start
6569

6670
# Or run the documentation site
6771
pnpm docs:dev
@@ -70,9 +74,14 @@ pnpm docs:dev
7074
Docker:
7175

7276
```bash
77+
mkdir -p docker/artifacts
78+
cp apps/objectos/dist/objectstack.json docker/artifacts/objectstack.json
7379
docker compose -f docker/docker-compose.yml up --build
7480
```
7581

82+
Docker Compose publishes ObjectOS on `http://localhost:3000` by default.
83+
Use `OBJECTOS_PORT=3200` to change the host port.
84+
7685
## History
7786

7887
The pre-rewrite codebase (a much larger multi-package implementation

‎apps/objectos/package.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"scripts": {
99
"dev": "objectstack dev",
1010
"build": "objectstack compile",
11-
"start": "objectstack serve",
11+
"start": "objectstack serve --port ${PORT:-3000}",
1212
"type-check": "tsc --noEmit"
1313
},
1414
"dependencies": {
@@ -17,7 +17,10 @@
1717
"@objectstack/spec": "^5.2.0",
1818
"@objectstack/metadata": "^5.2.0",
1919
"@objectstack/objectql": "^5.2.0",
20-
"@objectstack/cli": "^5.2.0"
20+
"@objectstack/cli": "^5.2.0",
21+
"@objectstack/driver-memory": "^5.2.0",
22+
"@objectstack/driver-sql": "^5.2.0",
23+
"@objectstack/driver-turso": "^5.2.0"
2124
},
2225
"devDependencies": {
2326
"typescript": "^5.7.0"

‎content/docs/architecture/index.mdx‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,61 @@
22
title: Architecture
33
---
44

5-
TODO: relationship to the ObjectStack control plane and Artifact API.
5+
# Architecture
6+
7+
ObjectOS is the **runtime distribution** of the ObjectStack ecosystem. It
8+
does not define protocol schemas and it does not write metadata. It loads
9+
an immutable artifact, hydrates an ObjectStack kernel, and serves the
10+
application described by that artifact.
11+
12+
## Runtime boundary
13+
14+
```text
15+
Application workspace
16+
objectstack compile
17+
|
18+
v
19+
dist/objectstack.json
20+
|
21+
| file mount or Artifact API
22+
v
23+
ObjectOS
24+
- validates artifact with upstream Zod schemas
25+
- hydrates ObjectKernel
26+
- auto-serves REST / UI metadata / tools
27+
- queries the business database
28+
```
29+
30+
## Control-plane boundary
31+
32+
In cloud-connected mode, ObjectOS talks to the control plane through the
33+
Artifact API only:
34+
35+
```text
36+
ObjectOS -> GET current Project Version artifact -> Control Plane
37+
```
38+
39+
ObjectOS must not open a direct connection to the control-plane database.
40+
This keeps the runtime deployable in customer networks and preserves a
41+
small, auditable protocol seam.
42+
43+
## Repository boundary
44+
45+
| Repository | Responsibility |
46+
|---|---|
47+
| `objectstack-ai/framework` | Protocol schemas, kernel, official drivers, services, Studio, control plane |
48+
| `objectstack-ai/objectos` | Runtime distribution, Docker/Helm, operations docs, enterprise plugin packaging |
49+
50+
ObjectOS consumes upstream `@objectstack/*` packages from npm. If a
51+
change requires protocol or kernel behavior, make that change in the
52+
framework first and then upgrade ObjectOS dependencies.
53+
54+
## Boot modes
55+
56+
| Mode | Source | Typical environment |
57+
|---|---|---|
58+
| Offline | `OS_ARTIFACT_FILE=/artifacts/objectstack.json` | Air-gapped customer deployment, local smoke test |
59+
| Cloud-connected | `OS_CLOUD_URL` + `OS_PROJECT_ID` | Hosted control plane, private cloud |
60+
61+
Both modes use the same runtime stack. The difference is only how the
62+
artifact is resolved.

‎content/docs/configure/index.mdx‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,67 @@
22
title: Configure
33
---
44

5-
TODO: env vars, plugin manifest, business DB drivers.
5+
# Configure
6+
7+
ObjectOS is configured by environment variables. The runtime has two
8+
boot modes: **offline** from a local artifact file, or **cloud-connected**
9+
from an ObjectStack control plane.
10+
11+
## Core variables
12+
13+
| Variable | Required | Default | Description |
14+
|---|---:|---|---|
15+
| `PORT` | No | `3000` | HTTP port inside the container. |
16+
| `OS_CACHE_DIR` | No | `/var/cache/objectos` | Runtime cache directory. Persist it across restarts. |
17+
| `OS_PROJECT_ID` | Cloud: Yes, File: No | `proj_local` in file mode | Project id used for hostname resolution and runtime identity. |
18+
| `OS_BUSINESS_DB_URL` | No | `file:/var/lib/objectos/data.db` in compose | Per-project business data location. |
19+
20+
## Offline / air-gapped mode
21+
22+
Offline mode reads a compiled ObjectStack artifact from disk:
23+
24+
| Variable | Required | Example |
25+
|---|---:|---|
26+
| `OS_ARTIFACT_FILE` | Yes | `/artifacts/objectstack.json` |
27+
| `OS_WATCH_ARTIFACT` | No | `1` while developing |
28+
29+
Docker Compose mounts `docker/artifacts` to `/artifacts`, so the default
30+
offline path is:
31+
32+
```bash
33+
docker/artifacts/objectstack.json
34+
```
35+
36+
## Cloud-connected mode
37+
38+
Cloud-connected mode fetches the current Project Version artifact from an
39+
ObjectStack control plane:
40+
41+
| Variable | Required | Example |
42+
|---|---:|---|
43+
| `OS_CLOUD_URL` | Yes | `https://cloud.example.com` |
44+
| `OS_PROJECT_ID` | Yes | `proj_xxxxxxxxxxxxx` |
45+
| `OS_CLOUD_API_KEY` | Optional | deployment token for private control planes |
46+
47+
ObjectOS only talks to the control plane over HTTP. It must not connect
48+
to the control-plane database directly.
49+
50+
## Business database
51+
52+
The runtime stores customer business rows outside the control-plane
53+
database. For a first local deployment, the compose default is enough:
54+
55+
```bash
56+
OS_BUSINESS_DB_URL=file:/var/lib/objectos/data.db
57+
```
58+
59+
For production, point this value at a managed or self-hosted database
60+
driver supported by the upstream `@objectstack/*` packages. Keep the
61+
business database lifecycle separate from ObjectOS container lifecycle.
62+
63+
## Enterprise plugins
64+
65+
Enterprise plugins belong in `packages/` and are composed in
66+
`apps/objectos/objectstack.config.ts`. Keep protocol schemas and kernel
67+
changes upstream in `objectstack-ai/framework`; this repository should
68+
only package runtime distribution behavior and deployment integrations.

‎content/docs/getting-started/index.mdx‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,74 @@ description: Run ObjectOS locally in under five minutes.
55

66
# Getting Started
77

8-
TODO.
8+
ObjectOS is the runtime you deploy for end customers. It does not author
9+
metadata; it consumes a compiled ObjectStack artifact and serves the API,
10+
UI metadata, permissions, workflows, and agent tool surfaces described by
11+
that artifact.
12+
13+
## Prerequisites
14+
15+
- Node.js 20+
16+
- pnpm 10+
17+
- Docker Desktop or another Docker-compatible runtime, if you want to run
18+
the container image locally
19+
- A compiled ObjectStack artifact (`dist/objectstack.json`) from an
20+
application repository
21+
22+
## Install dependencies
23+
24+
```bash
25+
pnpm install
26+
```
27+
28+
## Run the documentation site
29+
30+
```bash
31+
pnpm docs:dev
32+
```
33+
34+
The docs site runs on the first available Next.js port, usually
35+
`http://localhost:3000`.
36+
37+
## Run ObjectOS from a local artifact
38+
39+
Copy a compiled application artifact into the Docker artifact mount:
40+
41+
```bash
42+
mkdir -p docker/artifacts
43+
cp /path/to/app/dist/objectstack.json docker/artifacts/objectstack.json
44+
```
45+
46+
Then start ObjectOS:
47+
48+
```bash
49+
docker compose -f docker/docker-compose.yml up --build
50+
```
51+
52+
Open:
53+
54+
```text
55+
http://localhost:3000
56+
```
57+
58+
If you do not have Docker available, you can run the runtime directly:
59+
60+
```bash
61+
cd apps/objectos
62+
OS_ARTIFACT_FILE=../../docker/artifacts/objectstack.json pnpm start
63+
```
64+
65+
## Run ObjectOS against a control plane
66+
67+
Cloud-connected mode pulls the current Project Version artifact from an
68+
ObjectStack control plane instead of reading a local JSON file:
69+
70+
```bash
71+
OS_CLOUD_URL=https://cloud.example.com \
72+
OS_PROJECT_ID=proj_xxxxxxxxxxxxx \
73+
docker compose -f docker/docker-compose.yml up --build
74+
```
75+
76+
In this mode ObjectOS remains a runtime only: it talks to the control
77+
plane through the Artifact API, not by opening a connection to the
78+
control-plane database.

‎content/docs/install/index.mdx‎

Lines changed: 88 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,91 @@
22
title: Install
33
---
44

5-
TODO: docker run, docker-compose, Helm.
5+
# Install
6+
7+
ObjectOS can run as a local Node.js process, a Docker container, or a
8+
Kubernetes workload. Docker is the recommended starting point because it
9+
matches the production deployment shape.
10+
11+
## Docker Compose
12+
13+
1. Copy the example environment file:
14+
15+
```bash
16+
cp .env.example .env
17+
```
18+
19+
2. Put a compiled application artifact where the compose file expects it:
20+
21+
```bash
22+
mkdir -p docker/artifacts
23+
cp /path/to/app/dist/objectstack.json docker/artifacts/objectstack.json
24+
```
25+
26+
3. Start the runtime:
27+
28+
```bash
29+
docker compose -f docker/docker-compose.yml up --build
30+
```
31+
32+
4. Open the runtime:
33+
34+
```text
35+
http://localhost:3000
36+
```
37+
38+
The compose file persists runtime cache and local business data in Docker
39+
volumes:
40+
41+
| Volume | Purpose |
42+
|---|---|
43+
| `objectos-cache` | Artifact and runtime cache |
44+
| `objectos-data` | Local business database files |
45+
46+
## Docker image
47+
48+
Build the image manually:
49+
50+
```bash
51+
docker build -f docker/Dockerfile -t objectos:local .
52+
```
53+
54+
Run in offline mode:
55+
56+
```bash
57+
docker run --rm \
58+
-p 3000:3000 \
59+
-e OS_ARTIFACT_FILE=/artifacts/objectstack.json \
60+
-v "$PWD/docker/artifacts:/artifacts:ro" \
61+
-v objectos-cache:/var/cache/objectos \
62+
-v objectos-data:/var/lib/objectos \
63+
objectos:local
64+
```
65+
66+
Run in cloud-connected mode:
67+
68+
```bash
69+
docker run --rm \
70+
-p 3000:3000 \
71+
-e OS_CLOUD_URL=https://cloud.example.com \
72+
-e OS_PROJECT_ID=proj_xxxxxxxxxxxxx \
73+
-v objectos-cache:/var/cache/objectos \
74+
-v objectos-data:/var/lib/objectos \
75+
objectos:local
76+
```
77+
78+
## Local Node.js process
79+
80+
Use this for development only:
81+
82+
```bash
83+
pnpm install
84+
cd apps/objectos
85+
OS_ARTIFACT_FILE=../../docker/artifacts/objectstack.json pnpm start
86+
```
87+
88+
## Kubernetes / Helm
89+
90+
The official Helm chart will live under `helm/objectos/`. Until the chart
91+
is finalized, deploy the Docker image directly and provide the same
92+
environment variables documented in [Configure](/docs/configure).

0 commit comments

Comments
 (0)