From 3ac7e55d29ea48aeeb1bed95d1358f654f76e177 Mon Sep 17 00:00:00 2001 From: om986 Date: Wed, 14 Oct 2026 18:38:56 -0400 Subject: [PATCH] Document that the API applies migrations on startup. The install docs still told people to run om migrate after Compose, which the API now does itself. Co-authored-by: Cursor --- org-templates/github-profile-README.md | 2 +- src/pages/docs/cli.astro | 4 ++-- src/pages/docs/configuration.astro | 5 +++++ src/pages/docs/docker.astro | 30 ++++++++++++++++++-------- src/pages/docs/getting-started.astro | 20 +++++++++-------- src/pages/docs/index.astro | 2 +- src/pages/docs/kubernetes.astro | 11 ++++++++-- src/pages/docs/schema.astro | 2 +- 8 files changed, 51 insertions(+), 25 deletions(-) diff --git a/org-templates/github-profile-README.md b/org-templates/github-profile-README.md index 84fb970..0be860e 100644 --- a/org-templates/github-profile-README.md +++ b/org-templates/github-profile-README.md @@ -7,7 +7,7 @@ ```bash git clone https://github.com/OpenSourceOM/core.git cd core && cp .env.example .env && docker compose up -d -go build -o om ./cmd/om && ./om migrate && ./om scan demo && ./om rules run +go build -o om ./cmd/om && ./om scan demo && ./om rules run open http://localhost:8080 ``` diff --git a/src/pages/docs/cli.astro b/src/pages/docs/cli.astro index 92a4675..3a0a482 100644 --- a/src/pages/docs/cli.astro +++ b/src/pages/docs/cli.astro @@ -33,11 +33,11 @@ import DocsLayout from '@/layouts/DocsLayout.astro'; om migrate - Apply versioned SQL migrations. + Apply versioned SQL migrations. om serve does this on startup unless OM_AUTO_MIGRATE=false. om serve - Listen on OM_API_PORT and serve the API plus the console. + Apply pending migrations, then listen on OM_API_PORT and serve the API plus the console. om scan demo diff --git a/src/pages/docs/configuration.astro b/src/pages/docs/configuration.astro index 2ba0f2f..3909c07 100644 --- a/src/pages/docs/configuration.astro +++ b/src/pages/docs/configuration.astro @@ -52,6 +52,11 @@ import DocsLayout from '@/layouts/DocsLayout.astro'; 8080 om serve + + OM_AUTO_MIGRATE + true + om serve applies pending migrations before it listens. Set false when om migrate should be the only schema change. om migrate itself ignores this variable. + OM_ADMIN_EMAIL empty diff --git a/src/pages/docs/docker.astro b/src/pages/docs/docker.astro index 9bf0586..0e6580f 100644 --- a/src/pages/docs/docker.astro +++ b/src/pages/docs/docker.astro @@ -30,9 +30,19 @@ docker compose ps`}

Migrations

- The API container does not migrate on startup. From a checkout, with the CLI on the host: + om serve applies pending SQL files in migrations/ before it + listens. Compose starts the API with that command, so docker compose up -d + creates the schema. A later image applies only the files that are not already recorded in + schema_migrations. Startup logs applied database migrations or + database schema is current.

- 
{`go build -o om ./cmd/om
+  

+    Set OM_AUTO_MIGRATE=false in .env when a separate step should own
+    the schema. om migrate is also how you migrate when Compose is running Postgres
+    alone:
+  

+  
{`docker compose up -d postgres
+go build -o om ./cmd/om
 ./om migrate`}

   

     The CLI’s default database host is localhost, which is the published port.
@@ -61,14 +71,16 @@ docker compose ps`}

GET http://localhost:8080/v1/health returns - {`{"status":"ok","service":"opensourceom-api"}`} when the API process is up. It - does not check Postgres. A scan that fails on the database while health is ok means the CLI - and the container are not using the same connection settings. + {`{"status":"ok","service":"opensourceom-api"}`} when the API process is up and + Postgres answers a ping. om serve applies migrations before it listens, so a + healthy API has the current schema when OM_AUTO_MIGRATE is left on. A scan that + fails on the database while health is ok means the CLI and the container are not using the + same connection settings.

Useful commands

@@ -76,7 +88,7 @@ docker compose ps`} docker compose down docker compose down -v`}

- down -v deletes the Postgres volume. The next start is an empty database and - needs om migrate again. + down -v deletes the Postgres volume. The next API start is an empty database + and applies migrations again.

diff --git a/src/pages/docs/getting-started.astro b/src/pages/docs/getting-started.astro index b45d23d..f8ddbf0 100644 --- a/src/pages/docs/getting-started.astro +++ b/src/pages/docs/getting-started.astro @@ -6,12 +6,12 @@ import DocsLayout from '@/layouts/DocsLayout.astro';

Compose publishes Postgres on localhost:5432 and the API on - http://localhost:8080. The API container does not apply - schema migrations. The CLI does. + http://localhost:8080. The API applies pending + migrations before it listens.

Compose reads .env for the API container. The CLI does not. It defaults to @@ -58,12 +58,14 @@ docker compose up -d`} export that value into the shell you use for om.

-

Build the CLI and migrate

- 
{`go build -o om ./cmd/om
-./om migrate`}
+

Build the CLI

+ 
{`go build -o om ./cmd/om`}

- om migrate applies the SQL files in migrations/. Run it from the - repository root so the CLI can find that directory. + The API container runs om serve, which applies the SQL files in + migrations/ before it listens. A later start applies only files that are not + already recorded. When Compose is running Postgres without the API, run + om migrate from the repository root. Set OM_AUTO_MIGRATE=false on + the API when that command should be the only schema change.

Load the sample graph

diff --git a/src/pages/docs/index.astro b/src/pages/docs/index.astro index a737507..0af35d0 100644 --- a/src/pages/docs/index.astro +++ b/src/pages/docs/index.astro @@ -21,7 +21,7 @@ import DocsLayout from '@/layouts/DocsLayout.astro'; { question: 'Where do I start?', answer: - 'Install with Docker Compose, run om migrate, then om scan demo. That loads a sample graph with no cloud credentials. Real AWS, Azure, GCP, and Kubernetes scans use each provider’s default read-only credentials.', + 'Install with Docker Compose, then om scan demo. The API applies migrations when it starts. That loads a sample graph with no cloud credentials. Real AWS, Azure, GCP, and Kubernetes scans use each provider’s default read-only credentials.', }, ]} related={[ diff --git a/src/pages/docs/kubernetes.astro b/src/pages/docs/kubernetes.astro index 13720e2..5263c0e 100644 --- a/src/pages/docs/kubernetes.astro +++ b/src/pages/docs/kubernetes.astro @@ -15,8 +15,10 @@ import DocsLayout from '@/layouts/DocsLayout.astro'; 0.4.0. When bundled Postgres is enabled, an init container named wait-db runs pg_isready against {'{{release}}-opensourceom-postgres'}. A second init container runs - om migrate. The main container runs om serve. Readiness and - liveness probe GET /v1/health. With an external database, + om migrate. The main container runs om serve, which applies any + migrations still pending. api.autoMigrate (default true) sets + OM_AUTO_MIGRATE. Readiness and liveness probe GET /v1/health. + With an external database, wait-db is omitted and migrate still runs, so that host must accept connections before the pod can become Ready.

@@ -76,6 +78,11 @@ helm install om deploy/helm/opensourceom \\ production Written to OM_ENV. + + api.autoMigrate + true + Written to OM_AUTO_MIGRATE. om serve applies pending migrations. The init container still runs om migrate first. + api.smtp.host / api.smtp.port / api.smtp.from empty / 587 / empty diff --git a/src/pages/docs/schema.astro b/src/pages/docs/schema.astro index 191ef8c..c0585f1 100644 --- a/src/pages/docs/schema.astro +++ b/src/pages/docs/schema.astro @@ -17,7 +17,7 @@ import DocsLayout from '@/layouts/DocsLayout.astro';

Tables

- om migrate creates nodes and edges. Both rows carry + om migrate and om serve create nodes and edges. Both rows carry properties JSONB. Edges reference nodes with ON DELETE CASCADE. The unique key on an edge is (source_id, target_id, type).