Document that the API applies migrations on startup

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
 ```
 

src/pages/docs/cli.astro

@@ -33,11 +33,11 @@ import DocsLayout from '@/layouts/DocsLayout.astro';
       <tbody>
         <tr>
           <td><code>om migrate</code></td>
-          <td>Apply versioned SQL migrations.</td>
+          <td>Apply versioned SQL migrations. <code>om serve</code> does this on startup unless <code>OM_AUTO_MIGRATE=false</code>.</td>
         </tr>
         <tr>
           <td><code>om serve</code></td>
-          <td>Listen on <code>OM_API_PORT</code> and serve the API plus the console.</td>
+          <td>Apply pending migrations, then listen on <code>OM_API_PORT</code> and serve the API plus the console.</td>
         </tr>
         <tr>
           <td><code>om scan demo</code></td>

src/pages/docs/configuration.astro

@@ -52,6 +52,11 @@ import DocsLayout from '@/layouts/DocsLayout.astro';
           <td><code>8080</code></td>
           <td><code>om serve</code></td>
         </tr>
+        <tr>
+          <td><code>OM_AUTO_MIGRATE</code></td>
+          <td><code>true</code></td>
+          <td><code>om serve</code> applies pending migrations before it listens. Set <code>false</code> when <code>om migrate</code> should be the only schema change. <code>om migrate</code> itself ignores this variable.</td>
+        </tr>
         <tr>
           <td><code>OM_ADMIN_EMAIL</code></td>
           <td>empty</td>

src/pages/docs/docker.astro

@@ -30,9 +30,19 @@ docker compose ps`}</code></pre>
 
   <h2>Migrations</h2>
   <p>
-    The API container does not migrate on startup. From a checkout, with the CLI on the host:
+    <code>om serve</code> applies pending SQL files in <code>migrations/</code> before it
+    listens. Compose starts the API with that command, so <code>docker compose up -d</code>
+    creates the schema. A later image applies only the files that are not already recorded in
+    <code>schema_migrations</code>. Startup logs <code>applied database migrations</code> or
+    <code>database schema is current</code>.
   </p>
-  <pre><code>{`go build -o om ./cmd/om
+  <p>
+    Set <code>OM_AUTO_MIGRATE=false</code> in <code>.env</code> when a separate step should own
+    the schema. <code>om migrate</code> is also how you migrate when Compose is running Postgres
+    alone:
+  </p>
+  <pre><code>{`docker compose up -d postgres
+go build -o om ./cmd/om
 ./om migrate`}</code></pre>
   <p>
     The CLI’s default database host is <code>localhost</code>, which is the published port.
@@ -61,22 +71,24 @@ docker compose ps`}</code></pre>
   <ul>
     <li><code>POSTGRES_HOST=postgres</code> in the shell is the usual miss. That hostname exists only on the Compose network. Unset it, or set <code>POSTGRES_HOST=localhost</code>, for a CLI on the host.</li>
     <li>Password, user, and database must match what Compose used to initialize the volume. Changing <code>POSTGRES_PASSWORD</code> in <code>.env</code> after the first start does not alter an existing volume.</li>
-    <li>The API waits until Postgres is healthy. <code>om migrate</code> on the host does not. If it runs before the port is open, retry it.</li>
-    <li><code>relation "nodes" does not exist</code> means migrate has not been applied to this database.</li>
+    <li>The API waits until Postgres is healthy, then applies migrations. <code>om migrate</code> on the host does not wait. If it runs before the port is open, retry it.</li>
+    <li><code>relation "nodes" does not exist</code> means the API has not finished starting, or <code>OM_AUTO_MIGRATE=false</code> and <code>om migrate</code> has not been applied to this database.</li>
   </ul>
   <p>
     <code>GET http://localhost:8080/v1/health</code> returns
-    <code>{`{"status":"ok","service":"opensourceom-api"}`}</code> 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.
+    <code>{`{"status":"ok","service":"opensourceom-api"}`}</code> when the API process is up and
+    Postgres answers a ping. <code>om serve</code> applies migrations before it listens, so a
+    healthy API has the current schema when <code>OM_AUTO_MIGRATE</code> 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.
   </p>
 
   <h2>Useful commands</h2>
   <pre><code>{`docker compose logs -f api
 docker compose down
 docker compose down -v`}</code></pre>
   <p>
-    <code>down -v</code> deletes the Postgres volume. The next start is an empty database and
-    needs <code>om migrate</code> again.
+    <code>down -v</code> deletes the Postgres volume. The next API start is an empty database
+    and applies migrations again.
   </p>
 </DocsLayout>

src/pages/docs/getting-started.astro

@@ -6,12 +6,12 @@ import DocsLayout from '@/layouts/DocsLayout.astro';
 
 <DocsLayout
   title="Install a self-hosted security graph"
-  description="Install OpenSourceOM with Docker Compose, apply migrations, load the demo graph, and scan AWS, Azure, GCP, or Kubernetes."
+  description="Install OpenSourceOM with Docker Compose, load the demo graph, and scan AWS, Azure, GCP, or Kubernetes."
   faq={[
     {
       question: 'How do I install OpenSourceOM?',
       answer:
-        'Clone the OpenSourceOM/core repository, start Postgres and the API with Docker Compose, build the om CLI, and run om migrate. Then om scan demo loads a sample graph at http://localhost:8080.',
+        'Clone the OpenSourceOM/core repository and start Postgres and the API with Docker Compose. The API applies database migrations when it starts. Build the om CLI, then om scan demo loads a sample graph at http://localhost:8080.',
     },
     {
       question: 'Can I try OpenSourceOM without cloud credentials?',
@@ -48,8 +48,8 @@ cp .env.example .env
 docker compose up -d`}</code></pre>
   <p>
     Compose publishes Postgres on <code>localhost:5432</code> and the API on
-    <a href="http://localhost:8080">http://localhost:8080</a>. The API container does not apply
-    schema migrations. The CLI does.
+    <a href="http://localhost:8080">http://localhost:8080</a>. The API applies pending
+    migrations before it listens.
   </p>
   <p>
     Compose reads <code>.env</code> for the API container. The CLI does not. It defaults to
@@ -58,12 +58,14 @@ docker compose up -d`}</code></pre>
     export that value into the shell you use for <code>om</code>.
   </p>
 
-  <h2>Build the CLI and migrate</h2>
-  <pre><code>{`go build -o om ./cmd/om
-./om migrate`}</code></pre>
+  <h2>Build the CLI</h2>
+  <pre><code>{`go build -o om ./cmd/om`}</code></pre>
   <p>
-    <code>om migrate</code> applies the SQL files in <code>migrations/</code>. Run it from the
-    repository root so the CLI can find that directory.
+    The API container runs <code>om serve</code>, which applies the SQL files in
+    <code>migrations/</code> before it listens. A later start applies only files that are not
+    already recorded. When Compose is running Postgres without the API, run
+    <code>om migrate</code> from the repository root. Set <code>OM_AUTO_MIGRATE=false</code> on
+    the API when that command should be the only schema change.
   </p>
 
   <h2>Load the sample graph</h2>

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={[

src/pages/docs/kubernetes.astro

@@ -15,8 +15,10 @@ import DocsLayout from '@/layouts/DocsLayout.astro';
     <code>0.4.0</code>. When bundled Postgres is enabled, an init container named
     <code>wait-db</code> runs <code>pg_isready</code> against
     <code>{'{{release}}-opensourceom-postgres'}</code>. A second init container runs
-    <code>om migrate</code>. The main container runs <code>om serve</code>. Readiness and
-    liveness probe <code>GET /v1/health</code>. With an external database,
+    <code>om migrate</code>. The main container runs <code>om serve</code>, which applies any
+    migrations still pending. <code>api.autoMigrate</code> (default <code>true</code>) sets
+    <code>OM_AUTO_MIGRATE</code>. Readiness and liveness probe <code>GET /v1/health</code>.
+    With an external database,
     <code>wait-db</code> is omitted and <code>migrate</code> still runs, so that host must
     accept connections before the pod can become Ready.
   </p>
@@ -76,6 +78,11 @@ helm install om deploy/helm/opensourceom \\
           <td><code>production</code></td>
           <td>Written to <code>OM_ENV</code>.</td>
         </tr>
+        <tr>
+          <td><code>api.autoMigrate</code></td>
+          <td><code>true</code></td>
+          <td>Written to <code>OM_AUTO_MIGRATE</code>. <code>om serve</code> applies pending migrations. The init container still runs <code>om migrate</code> first.</td>
+        </tr>
         <tr>
           <td><code>api.smtp.host</code> / <code>api.smtp.port</code> / <code>api.smtp.from</code></td>
           <td>empty / <code>587</code> / empty</td>

src/pages/docs/schema.astro

@@ -17,7 +17,7 @@ import DocsLayout from '@/layouts/DocsLayout.astro';
 
   <h2>Tables</h2>
   <p>
-    <code>om migrate</code> creates <code>nodes</code> and <code>edges</code>. Both rows carry
+    <code>om migrate</code> and <code>om serve</code> create <code>nodes</code> and <code>edges</code>. Both rows carry
     <code>properties JSONB</code>. Edges reference nodes with <code>ON DELETE CASCADE</code>.
     The unique key on an edge is <code>(source_id, target_id, type)</code>.
   </p>