cortex/docs/operations.md

Operations Guide

Cortex local operations are PowerShell-only.

Dev Stack

The dev stack is named cortex.

Container	Purpose
cortex-db	PostgreSQL with pgvector.
cortex-embeddings	Local embedding service.
cortex-app	.NET 10 MCP server.
cortex-web	Optional Blazor web UI.

Test Stack

The test stack is named cortex-test.

Container	Purpose
cortex-test-db	Isolated PostgreSQL with pgvector.
cortex-test-embeddings	Isolated embedding service.
cortex-test-app	Isolated MCP server under test.
cortex-test-web	Optional isolated Blazor web UI.

The test stack uses different ports and a different database volume so it can run beside the dev stack.

Script Reference

Build

.\scripts\build.ps1

Restores packages, builds the solution, and builds the local app Docker image.

Deploy All

.\scripts\deploy-all.ps1

Starts db and embeddings, builds the app image, applies migrations, and starts the app.

Deploy Individual Services

.\scripts\deploy-db.ps1
.\scripts\deploy-embeddings.ps1
.\scripts\deploy-app.ps1

Use these when iterating on one part of the stack.

Deploy Optional Web UI

.\scripts\deploy-web.ps1

Starts the dev dependencies, applies migrations, and starts the Blazor web UI at:

http://localhost:5118

Stop only the web UI:

.\scripts\stop-web.ps1

Migrate

.\scripts\migrate-db.ps1

Runs the app in migration mode and applies EF Core migrations.

Seed

.\scripts\seed-db.ps1

Runs the app in seed mode.

Logs

.\scripts\logs.ps1
.\scripts\logs.ps1 -Service app
.\scripts\logs.ps1 -Service db
.\scripts\logs.ps1 -Service embeddings
.\scripts\logs.ps1 -Service app -Follow

Stop

.\scripts\stop-all.ps1

Stops dev services without deleting volumes.

Reset Dev Database

.\scripts\reset-db.ps1 -Force

Deletes the dev PostgreSQL volume and recreates the database container.

Test Deployment

.\scripts\deploy-test.ps1

Starts the isolated test stack and waits for http://localhost:5217/health.

Test Web UI

.\scripts\deploy-test-web.ps1

Starts the optional web UI against the isolated test stack:

http://localhost:5218

Stop it with:

.\scripts\stop-test-web.ps1

Integration Test Pipeline

.\scripts\test-integration.ps1

By default this:

1. Resets the test database.
2. Deploys the test stack.
3. Runs integration tests.
4. Stops the test stack.

Useful variants:

.\scripts\test-integration.ps1 -KeepRunning
.\scripts\test-integration.ps1 -NoReset
.\scripts\test-integration.ps1 -Filter "FullyQualifiedName~SearchTests"

Reset Test Database

.\scripts\reset-test.ps1 -Force

Deletes only the test PostgreSQL volume.

Docker Compose Files

File	Purpose
docker-compose.yml	Dev stack.
docker-compose.test.yml	Isolated integration test stack.

The test compose file is standalone on purpose. It does not inherit from the dev compose file, so ports, container names, and volumes cannot accidentally overlap.

The web UI services are behind the Docker Compose ui profile, so they do not start during normal MCP-only deployment.