# 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

```powershell
.\scripts\build.ps1
```

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

### Deploy All

```powershell
.\scripts\deploy-all.ps1
```

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

### Deploy Individual Services

```powershell
.\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

```powershell
.\scripts\deploy-web.ps1
```

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

```text
http://localhost:5118
```

Stop only the web UI:

```powershell
.\scripts\stop-web.ps1
```

### Migrate

```powershell
.\scripts\migrate-db.ps1
```

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

### Seed

```powershell
.\scripts\seed-db.ps1
```

Runs the app in seed mode.

### Logs

```powershell
.\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

```powershell
.\scripts\stop-all.ps1
```

Stops dev services without deleting volumes.

### Reset Dev Database

```powershell
.\scripts\reset-db.ps1 -Force
```

Deletes the dev PostgreSQL volume and recreates the database container.

### Test Deployment

```powershell
.\scripts\deploy-test.ps1
```

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

### Test Web UI

```powershell
.\scripts\deploy-test-web.ps1
```

Starts the optional web UI against the isolated test stack:

```text
http://localhost:5218
```

Stop it with:

```powershell
.\scripts\stop-test-web.ps1
```

### Integration Test Pipeline

```powershell
.\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:

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

### Reset Test Database

```powershell
.\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.