mosaicstack/stack
1
0
Fork 0
Code Issues 58 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

docs(#771): hold unsafe database startup routes

Browse Source
This commit is contained in:
Hermes Agent
2026-07-15 06:59:34 -05:00
parent b0bc036dfb
commit 981183eb7e
12 changed files with 216 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files

402
docs/guides/deployment.md
View File

@@ -1,374 +1,70 @@
# Deployment Guide
This guide covers deploying Mosaic in two modes: **Docker Compose** (recommended for quick setup) and **bare-metal** (production, full control).
> **Status: non-operative for PostgreSQL, federated, and bare-metal production.** The checked-in
> Compose PostgreSQL service mounts legacy initialization SQL and the KBN-101 bootstrap, runner,
> secret-renderer, and process-exec interfaces do not exist yet. This page does not authorize a
> production deployment, database initialization, manual DDL, secret provisioning, or service
> activation.
---
## Current safe local route
## Prerequisites
| Dependency | Minimum version | Notes |
| ---------------- | --------------- | ---------------------------------------------- |
| Node.js | 22 LTS | Required for ESM + `--experimental-vm-modules` |
| pnpm | 9 | `npm install -g pnpm` |
| PostgreSQL | 17 | Must have the `pgvector` extension |
| Valkey | 8 | Redis-compatible; Redis 7+ also works |
| Docker + Compose | v2 | For the Docker Compose path only |
---
## Docker Compose Deployment (Quick Start)
The `docker-compose.yml` at the repository root starts PostgreSQL 17 (with pgvector), Valkey 8, an OpenTelemetry Collector, and Jaeger.
### 1. Clone and configure
Use PGlite only for current in-process data-layer work; it requires no PostgreSQL. A Gateway/Web
local process is held because its unguarded dotenv loader can inherit a daemon PostgreSQL DSN and
reach runtime DDL. If a local queue service is useful, start only Valkey:
```bash
git clone <repo-url> mosaic
cd mosaic
cp .env.example .env
docker compose up -d valkey
```
Edit `.env`. The minimum required change is:
This command intentionally does not start PostgreSQL. Do not run a broad Compose start, use its
PostgreSQL initialization mount, infer that current Compose is a production/federated route, or
start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.
```dotenv
BETTER_AUTH_SECRET=<output of: openssl rand -base64 32>
```
## PostgreSQL and federated activation (future procedure)
### 2. Start infrastructure services
PostgreSQL local, federated, Compose, and bare-metal production activation are held until these
artifacts land and pass their independent gates:
```bash
docker compose up -d
```
1. **KBN-101-00** external privileged bootstrap artifact;
2. **KBN-101-03** sole `mosaic-db-migrator` runner and verified-readiness artifact; and
3. **KBN-101-05** Vault/secret-renderer-backed deployment and consumer-isolation artifact.
Services and their ports:
The required future order is:
| Service | Default port |
| --------------------- | ------------------------ |
| PostgreSQL | `localhost:5433` |
| Valkey | `localhost:6380` |
| OTEL Collector (HTTP) | `localhost:4318` |
| OTEL Collector (gRPC) | `localhost:4317` |
| Jaeger UI | `http://localhost:16686` |
> external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
> `mosaic-db-migrator --verify` → Gateway/Compose readiness
Override host ports via `PG_HOST_PORT` and `VALKEY_HOST_PORT` in `.env` if the defaults conflict.
This is a future activation specification, not an executable procedure. Do not invoke the named
runner, start PostgreSQL, or substitute a Compose/init/manual-SQL route until the owned artifacts
are implemented and reviewed.
### 3. Install dependencies
## Future production secret and unit boundary (schematic only)
```bash
pnpm install
```
No current bare-metal production unit or command is published. KBN-101-05 must supply a reviewed,
generation-pinned Vault renderer and a process-exec or systemd `LoadCredential` interface before
production units can exist. The interface must preserve these exact consumer boundaries:
### 4. Initialize the database
| Consumer | May receive | Must never receive |
| ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Gateway/runtime | Its own runtime URL and DB client CA at process exec | Migrator URL, importer URL/version, attestation material, signing key, PostgreSQL private key |
| One-shot migrator | Its own migration URL, DB client CA, and runner-only signing capability | Runtime URL, importer consumer copy, Gateway/private PostgreSQL keys |
| Data importer | Its own immutable URL/version copies, importer CA, pinned public key, and sealed attestation | Runtime/migrator URLs, signing key, shared writable mount |
| PostgreSQL | Its own server certificate/key and only its approved server material | Application, migrator, importer, or Gateway secrets |
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
A future unit specification is non-executable until KBN-101-05 supplies it. It must obtain
credentials through the renderer’s Vault generation and process-exec/`LoadCredential` boundary;
it must not place credentials in a production environment file, a monorepo auto-load path, a shell
export, command arguments, logs, or a manual secret-activation lifecycle instruction. Rotation and
process replacement semantics must be delivered by the reviewed renderer/interface with generation,
consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvised in this guide.
This is the sole PostgreSQL DDL/readiness control plane. It receives migration-only credentials
through deployment secret mounts and accepts no URL, SQL, schema, or role argv.
## Readiness and troubleshooting status
### 5. Build all packages
Until the future procedure is implemented, do not diagnose PostgreSQL with ad hoc SQL, connection
strings, or initialization scripts. The future sanitized `mosaic-db-migrator --verify` readiness
artifact is the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass.
For local PGlite development, diagnose application behavior without introducing a PostgreSQL
connection.
```bash
pnpm build
```
### 6. Start the gateway
```bash
pnpm --filter @mosaicstack/gateway dev
```
Or for production (after build):
```bash
node apps/gateway/dist/main.js
```
### 7. Start the web app
```bash
# Development
pnpm --filter @mosaicstack/web dev
# Production (after build)
pnpm --filter @mosaicstack/web start
```
The web app runs on port `3000` by default.
---
## Bare-Metal Deployment
Use this path when you want to manage PostgreSQL and Valkey yourself (e.g., existing infrastructure, managed cloud databases).
### Step 1 — Install system dependencies
```bash
# Node.js 22 via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
# pnpm
npm install -g pnpm
# PostgreSQL 17 with pgvector (Debian/Ubuntu example)
sudo apt-get install -y postgresql-17 postgresql-17-pgvector
# Valkey
# Follow https://valkey.io/download/ for your distribution
```
### Step 2 — Provision the database
Do not run ad hoc SQL, create application roles, or create extensions from this guide. The
external reviewed bootstrap artifact provisions roles/pgvector, then the migration Job runs
`mosaic-db-migrator --run` and `mosaic-db-migrator --verify` over verified TLS. This guide does
not authorize a plaintext, owner-runtime, or manual-extension bootstrap.
### Step 3 — Clone and configure
```bash
git clone <repo-url> /opt/mosaic
cd /opt/mosaic
```
Production deployment does **not** read a committed or local `.env` file. Use the reviewed
secret renderer/deployment control plane: it injects runtime secrets only at process exec,
migration secrets only to the one-shot runner, and non-secret endpoint configuration separately.
Validate required values at startup; never write a DSN or BetterAuth secret into this guide or a
production filesystem `.env`.
### Step 4 — Install dependencies and build
```bash
pnpm install
pnpm build
```
### Step 5 — Run database migrations
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
The one-shot migrator alone receives the migration secret; Gateway/runtime never receives it.
### Step 6 — Start the gateway
```bash
node apps/gateway/dist/main.js
```
The gateway reads `.env` from the monorepo root automatically (via `dotenv` in `main.ts`).
### Step 7 — Start the web app
```bash
# Next.js standalone output
node apps/web/.next/standalone/server.js
```
The standalone build is self-contained; it does not require `node_modules` to be present at runtime.
### Step 8 — Configure a reverse proxy
#### Nginx example
```nginx
# /etc/nginx/sites-available/mosaic
# Gateway API
server {
listen 443 ssl;
server_name your-domain.example.com;
ssl_certificate /etc/ssl/certs/your-domain.crt;
ssl_certificate_key /etc/ssl/private/your-domain.key;
# WebSocket support (for chat.gateway.ts / Socket.IO)
location /socket.io/ {
proxy_pass http://127.0.0.1:14242;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# REST + auth
location / {
proxy_pass http://127.0.0.1:14242;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# Web app (optional — serve on a subdomain or a separate server block)
server {
listen 443 ssl;
server_name app.your-domain.example.com;
ssl_certificate /etc/ssl/certs/your-domain.crt;
ssl_certificate_key /etc/ssl/private/your-domain.key;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
#### Caddy example
```caddyfile
# /etc/caddy/Caddyfile
your-domain.example.com {
reverse_proxy /socket.io/* localhost:14242 {
header_up Upgrade {http.upgrade}
header_up Connection {http.connection}
}
reverse_proxy localhost:14242
}
app.your-domain.example.com {
reverse_proxy localhost:3000
}
```
---
## Production Considerations
### systemd Services
Create a service unit for each process.
**Gateway** — `/etc/systemd/system/mosaic-gateway.service`:
```ini
[Unit]
Description=Mosaic Gateway
After=network.target postgresql.service
[Service]
Type=simple
User=mosaic
WorkingDirectory=/opt/mosaic
EnvironmentFile=/opt/mosaic/.env
ExecStart=/usr/bin/node apps/gateway/dist/main.js
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
**Web app** — `/etc/systemd/system/mosaic-web.service`:
```ini
[Unit]
Description=Mosaic Web App
After=network.target mosaic-gateway.service
[Service]
Type=simple
User=mosaic
WorkingDirectory=/opt/mosaic/apps/web
EnvironmentFile=/opt/mosaic/.env
ExecStart=/usr/bin/node .next/standalone/server.js
Environment=PORT=3000
Environment=HOSTNAME=127.0.0.1
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now mosaic-gateway mosaic-web
```
### Log Management
Gateway and web app logs go to systemd journal by default. View with:
```bash
journalctl -u mosaic-gateway -f
journalctl -u mosaic-web -f
```
Rotate logs by configuring `journald` in `/etc/systemd/journald.conf`:
```ini
SystemMaxUse=500M
MaxRetentionSec=30day
```
### Security Checklist
- Set `BETTER_AUTH_SECRET` to a cryptographically random value (`openssl rand -base64 32`).
- Restrict `GATEWAY_CORS_ORIGIN` to your exact frontend origin — do not use `*`.
- Run services as a dedicated non-root system user (e.g., `mosaic`).
- Firewall: only expose ports 80/443 externally; keep 14242 and 3000 bound to `127.0.0.1`.
- Set `AGENT_FILE_SANDBOX_DIR` to a directory outside the application root to prevent agent tools from accessing source code.
- If using `AGENT_USER_TOOLS`, enumerate only the tools non-admin users need.
---
## Troubleshooting
### Gateway fails to start — "BETTER_AUTH_SECRET is required"
`BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
### Runtime database connection refused
Verify PostgreSQL service/TLS readiness and the deployment-mounted runtime secret reference. Do
not print or test a DSN from a shell. Run the sanitized `mosaic-db-migrator --verify` readiness
procedure; if pgvector or schema verification fails, stop and remediate through the reviewed
bootstrap/runner control plane. Manual extension SQL is unavailable.
### Valkey / Redis connection refused
Check the URL in `VALKEY_URL`. The Docker Compose default is port `6380`.
```bash
redis-cli -u "$VALKEY_URL" ping
```
### WebSocket connections fail in production
Ensure your reverse proxy forwards the `Upgrade` and `Connection` headers. See the Nginx/Caddy examples above.
### Ollama models not appearing
Set `OLLAMA_BASE_URL` to the URL where Ollama is running (e.g., `http://localhost:11434`) and set `OLLAMA_MODELS` to a comma-separated list of model IDs you have pulled.
```bash
ollama pull llama3.2
```
### OTEL traces not appearing in Jaeger
Verify the collector is reachable at `OTEL_EXPORTER_OTLP_ENDPOINT`. With Docker Compose the default is `http://localhost:4318`. Check `docker compose ps` and `docker compose logs otel-collector`.
### Summarization / embedding features not working
These features require `OPENAI_API_KEY` to be set, or you must point `SUMMARIZATION_API_URL` / `EMBEDDING_API_URL` to an OpenAI-compatible endpoint (e.g., a local Ollama instance with an embeddings model).
Non-database local services may be inspected with their ordinary local health/log tools. Those
checks do not certify PostgreSQL, federated deployment, or production readiness.

159
docs/guides/dev-guide.md
View File

@@ -39,7 +39,7 @@ mosaic-mono-v1/
│ ├── queue/ # Valkey-backed task queue
│ └── types/ # Shared TypeScript types
├── docker/ # Dockerfile(s) for containerized deployment
├── infra/ # Infra config (OTEL collector, pg-init scripts)
├── infra/ # Infrastructure configuration (for example, OTEL collector)
├── docker-compose.yml # Local services (Postgres, Valkey, OTEL, Jaeger)
└── CLAUDE.md # Project conventions for AI coding agents
```
@@ -86,75 +86,54 @@ cd mosaic-mono-v1
pnpm install
```
### 2. Start Infrastructure Services
### 2. Use the local PGlite tier
The supported local tier is in-process PGlite and requires no PostgreSQL service. Leave
`DATABASE_URL` unset for this route. Its default local configuration uses PGlite and performs no
external database probe.
If a local queue service is useful, start only that non-PostgreSQL service:
```bash
docker compose up -d
docker compose up -d valkey
```
This starts:
Do not use the current Compose PostgreSQL service: it mounts legacy `infra/pg-init` SQL and is
not qualified for KBN-101. Start OTEL Collector or Jaeger individually only when needed and
without starting PostgreSQL.
| Service | Port | Description |
| ------------------------ | -------------- | -------------------- |
| PostgreSQL 17 + pgvector | `5433` (host) | Primary database |
| Valkey 8 | `6380` (host) | Queue and cache |
| OpenTelemetry Collector | `4317`, `4318` | OTEL gRPC and HTTP |
| Jaeger | `16686` | Distributed trace UI |
### 3. Gateway/Web local process (held)
### 3. Configure Environment
Do not start the current Gateway or web process as a local PGlite route. Gateway first loads the
daemon configuration and then project environment files without a tier guard; a pre-existing
`DATABASE_URL` can select PostgreSQL, where current startup still reaches runtime DDL/migrations.
Creating a root `.env` that omits `DATABASE_URL` does not make this safe, so neither a local
credential file nor a web environment file is a current developer procedure.
Create a `.env` file in the monorepo root:
PGlite remains the supported in-process data-layer implementation, and the optional Valkey command
above remains safe because it does not start PostgreSQL. A safe Gateway/Web local procedure is held
until KBN-101-02 rejects a daemon, inherited, root, or app-local PostgreSQL DSN and any non-local
tier before connection or DDL; KBN-101-05 then supplies the production renderer/Vault process-exec
or `LoadCredential` boundary.
```env
# Runtime database connection (local-development placeholder only; never a production secret)
# KBN-101 production-like runtime injects DATABASE_URL from its dedicated secret mount.
# Importer URL/version are separate generation-pinned files and never env-exported.
DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
### 4. PostgreSQL and federated activation (held)
# Auth (required — generate a random 32+ char string)
BETTER_AUTH_SECRET=change-me-to-a-random-secret
PostgreSQL local and federated deployment are held until KBN-101-00 (external bootstrap),
KBN-101-03 (runner), and KBN-101-05 (renderer-backed deployment) land. The following is the
**future activation order, not a command sequence that is currently executable**:
# Gateway
GATEWAY_PORT=14242
GATEWAY_CORS_ORIGIN=http://localhost:3000
external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
`mosaic-db-migrator --verify` → Gateway/Compose readiness.
# Web
NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
Neither current Compose nor this development guide authorizes PostgreSQL initialization SQL,
manual DDL, or a pre-runner start.
# Optional: Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODELS=llama3.2
```
### 5. Gateway/Web start (held)
The gateway loads `.env` from the monorepo root via `dotenv` at startup
(`apps/gateway/src/main.ts`).
### 4. Prepare the PostgreSQL Schema
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
KBN-101 makes this the sole PostgreSQL DDL/readiness sequence. Direct schema push is not an
operator workflow; a disposable local experiment is separately guarded and cannot use a
production-like tier or URL.
### 5. Start the Gateway
```bash
pnpm --filter @mosaicstack/gateway exec tsx src/main.ts
```
The gateway starts on port `14242` by default.
### 6. Start the Web App
```bash
pnpm --filter @mosaicstack/web dev
```
The web app starts on port `3000` by default.
No Gateway/Web start command is currently authorized for the local PGlite route. Do not use root
`pnpm dev` as a workaround: it additionally starts configured integrations and cannot establish the
required local-tier/DSN isolation. Resume this section only after KBN-101-02 provides its
fail-closed local-startup evidence.
---
@@ -304,26 +283,13 @@ Implement a standard MCP server that exposes tools via the streamable HTTP
transport or SSE transport. The server must accept connections at a `/mcp`
endpoint.
### 2. Configure `MCP_SERVERS`
### 2. Gateway MCP configuration (held)
In your `.env`:
```env
MCP_SERVERS='[{"name":"my-server","url":"http://localhost:3001/mcp"}]'
```
With authentication:
```env
MCP_SERVERS='[{"name":"secure-server","url":"http://my-server/mcp","headers":{"Authorization":"Bearer token"}}]'
```
### 3. Restart the Gateway
On startup, `McpClientService` (`apps/gateway/src/mcp-client/mcp-client.service.ts`)
connects to each configured server, calls `tools/list`, and bridges the results
to Pi SDK `ToolDefinition` format. These tools become available in all new agent
sessions.
Do not configure MCP endpoint credentials, write them to a local environment file, or restart the
Gateway from this guide. Gateway/Web startup is held until KBN-101-02 supplies fail-closed
local-tier/DSN isolation and KBN-101-05 supplies the renderer/Vault process-exec or
`LoadCredential` secret-consumer interface. The future authenticated MCP route requires verified
HTTPS and certificate validation; plaintext bearer-token examples are forbidden.
### Tool Naming
@@ -359,44 +325,31 @@ The schema lives in a single file:
The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
### Development: Prepare Schema
### PostgreSQL schema work (held)
Prepare a PostgreSQL development target through the same sole runner:
Do not prepare or run a PostgreSQL target from this branch. The sole runner, bootstrap, and
renderer are future KBN-101 artifacts, not current commands. When KBN-101-00/-03/-05 land, the
owned activation documentation will require external bootstrap → TLS/roles → runner `--run` →
runner `--verify` → Gateway/Compose readiness.
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
### Generating migration artifacts
### Generating Migrations
For production-safe, versioned changes:
```bash
pnpm --filter @mosaicstack/db db:generate
```
This creates a new SQL migration file in `packages/db/drizzle/`.
### Running Migrations
```bash
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
`pnpm --filter @mosaicstack/db db:generate` is an offline artifact-generation command. It does
not authorize connecting to or initializing PostgreSQL. A future reviewed PostgreSQL procedure
will determine when its output is applied.
### Drizzle Config
Config is at `packages/db/drizzle.config.ts`. The schema file path and output
directory are defined there.
Config is at `packages/db/drizzle.config.ts`. The schema file path and output directory are
defined there.
### Adding a New Table
1. Add the table definition to `packages/db/src/schema.ts`.
2. Export it from `packages/db/src/index.ts`.
3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`, then run
`mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. Direct schema push is not a
production-like workflow and the migration runner accepts no URL/SQL/schema/role argv.
3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`.
4. Do not apply it to PostgreSQL until the future KBN-101 activation artifacts and their owned
procedure are available. Direct schema push is not a production-like workflow.
---