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

docs(#771): bind tier importer to verified target

Browse Source
This commit is contained in:
Hermes Agent
2026-07-15 03:58:02 -05:00
parent fcb73352ed
commit b1a4ef5ce7
18 changed files with 260 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/guides/deployment.md
View File

@@ -61,9 +61,13 @@ pnpm install
### 4. Initialize the database
```bash
pnpm --filter @mosaicstack/db db:migrate
mosaic-db-migrator --run
mosaic-db-migrator --verify
```
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.
### 5. Build all packages
```bash
@@ -118,34 +122,25 @@ sudo apt-get install -y postgresql-17 postgresql-17-pgvector
# Follow https://valkey.io/download/ for your distribution
```
### Step 2 — Create the database
### Step 2 — Provision the database
```sql
-- Run as the postgres superuser
CREATE USER mosaic WITH PASSWORD 'change-me';
CREATE DATABASE mosaic OWNER mosaic;
\c mosaic
CREATE EXTENSION IF NOT EXISTS vector;
```
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
cp .env.example .env
```
Edit `/opt/mosaic/.env`. Required fields:
```dotenv
DATABASE_URL=postgresql://mosaic:<password>@localhost:5432/mosaic
VALKEY_URL=redis://localhost:6379
BETTER_AUTH_SECRET=<openssl rand -base64 32>
BETTER_AUTH_URL=https://your-domain.example.com
GATEWAY_CORS_ORIGIN=https://your-domain.example.com
NEXT_PUBLIC_GATEWAY_URL=https://your-domain.example.com
```
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
@@ -157,9 +152,12 @@ pnpm build
### Step 5 — Run database migrations
```bash
pnpm --filter @mosaicstack/db db:migrate
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
@@ -340,20 +338,12 @@ MaxRetentionSec=30day
`BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
### `DATABASE_URL` connection refused
### Runtime database connection refused
Verify PostgreSQL is running and the port matches. The Docker Compose default is `5433`; bare-metal typically uses `5432`.
```bash
psql "$DATABASE_URL" -c '\conninfo'
```
### pgvector extension missing
```sql
\c mosaic
CREATE EXTENSION IF NOT EXISTS vector;
```
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