182 lines
3.4 KiB
Markdown
182 lines
3.4 KiB
Markdown
# 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.
|