SlipItIn/openwiki/operations/runbook.md

type, title, description, tags

type	title	description	tags
Runbook	Operations, Environment Setup & Testing Guidance	Operational guide for launching SlipItIn with .NET Aspire, running EF Core PostgreSQL migrations, configuring JWT secrets, and executing tests.	operations runbook spire postgresql migrations testing

Operations, Environment Setup & Testing Guidance

This runbook provides actionable instructions for local development setup, starting services via .NET Aspire, executing Entity Framework Core migrations, configuring environment keys, and running tests.

This guide configures environment parameters for the backend architecture, manages database migrations for entities in the domain model, verifies real-time event flows defined in the workflow guide, and references source entrypoints cataloged in the source map.

---

1. Local Development Environment Setup

Prerequisites

• .NET 10 SDK (Installed and verified via dotnet --version).
• Docker Desktop or Podman (Required by .NET Aspire to run the PostgreSQL container).
• Workloads: .NET Aspire workload and .NET MAUI workload (dotnet workload install aspire maui).

Starting the Distributed Application with Aspire

Run the Aspire orchestrator project:

dotnet run --project SlipItIn.AppHost/SlipItIn.AppHost.csproj

What happens during launch:

1. Aspire launches a PostgreSQL container (pgsql/postgresdb).
2. Aspire builds and starts SlipItIn.Server.
3. Program.cs automatically executes EF Core migrations (db.Database.Migrate()), creating database tables if they do not exist.
4. Aspire Dashboard opens in your web browser, displaying live metrics, OpenTelemetry traces, and structured logs for all services.

---

2. Configuration & Secrets Management

Configuration settings are loaded from appsettings.json and environment variables.

Key Configuration Keys (SlipItIn.Server)

Key	Default Value	Description
Jwt:Key	YourSuperSecretKeyThatIsAtLeast32CharactersLong!	Secret signing key for JWT tokens (Must be >= 256 bits).
Jwt:Issuer	SlipItInServer	Token issuer claim.
Jwt:Audience	SlipItInClient	Token audience claim.
Jwt:ExpirationMinutes	1440 (24 hours)	JWT token lifespan.
ConnectionStrings:postgresdb	Configured via Aspire	PostgreSQL connection string.

Production Configuration Security

In production deployment, override Jwt:Key using environment variables or user secrets (dotnet user-secrets):

dotnet user-secrets set "Jwt:Key" "YOUR_HIGH_ENTROPY_PRODUCTION_SECRET_KEY_HERE" --project SlipItIn.Server

---

3. Entity Framework Core Migrations

When altering models in SlipItIn.Shared/Models/ or SlipItInDbContext.cs:

Adding a New Migration

Run the EF Core CLI from the repository root:

dotnet ef migrations add <MigrationName> --project SlipItIn.Server --startup-project SlipItIn.Server

Applying Migrations Manually

While Program.cs applies migrations at startup (db.Database.Migrate()), migrations can also be manually applied via command line:

dotnet ef database update --project SlipItIn.Server --startup-project SlipItIn.Server

---

4. Testing Guidance & Verification Scenarios

When developing or extending SlipItIn features, verify the core architecture through targeted test scenarios specified in Agents/Architecture.md:

1. JWT Authentication & Claims Tests

• Test Objective: Verify GameHub rejects unauthenticated WebSocket connections or missing token query parameters.
• Verification: Connect to /hubs/game without ?access_token=... or with an expired token. Confirm SignalR connection is terminated with 401 Unauthorized.

2. Player Access Authorization Tests

• Test Objective: Verify Player A cannot manipulate Player B's cards or state.
• Verification: Authenticate as User A and attempt to call GameHub.SubmitSlip(gameId, playerBId, cardId). Verify that ValidatePlayerAccessAsync throws UnauthorizedAccessException and returns an error response.

3. Concurrency & Race Condition Tests

• Test Objective: Confirm IDbContextFactory handles simultaneous WebSocket calls without thread collision.
• Verification: Simulate 5 parallel calls to GameHub.ChallengeSlip() or SubmitSlip() across multiple clients. Verify that all calls complete cleanly without InvalidOperationException from DbContext.

4. Data Privacy Isolation Verification

• Test Objective: Confirm card text is never broadcast in public group messages.
• Verification: Capture SignalR PlayerJoined and GameStateUpdated payloads. Inspect JSON content to confirm only CardCount is present and no phrase card Text is leaked.

5. False Accusation Penalty Verification

• Test Objective: Verify penalty card transfer when a challenge is rejected.
• Verification: Submit a challenge against a valid slip, then call ResolveChallenge(challengeId, approved: false). Verify in the database that PlayerCard.PlayerId is reassigned to the challenger's PlayerId.