|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Crucible Development is a Development Container and .NET Aspire orchestration environment for the Crucible platform - a cybersecurity training and simulation platform developed by Carnegie Mellon University's Software Engineering Institute (SEI). |
| 8 | + |
| 9 | +This is a **meta-repository** that orchestrates 30+ external repositories cloned into `/mnt/data/crucible/`. The main orchestrator (`Crucible.AppHost`) manages all microservices using .NET Aspire. |
| 10 | + |
| 11 | +## Architecture |
| 12 | + |
| 13 | +### Core Components |
| 14 | +- **Crucible.AppHost** - Central .NET Aspire orchestrator that manages all services |
| 15 | +- **PostgreSQL** - Centralized multi-tenant database (container: `crucible-postgres`) |
| 16 | +- **Keycloak** - OpenID Connect identity provider (ports 8080/8443) |
| 17 | +- **MkDocs** - Documentation server (port 8000) |
| 18 | +- **PGAdmin** - Database admin UI (port 33000) |
| 19 | + |
| 20 | +### Microservices (in `/mnt/data/crucible/`) |
| 21 | +| Service | Purpose | Ports | |
| 22 | +|---------|---------|-------| |
| 23 | +| Player API/UI | Main learning platform | 4301 | |
| 24 | +| Player VM API/UI | Virtual machine management | 4303 | |
| 25 | +| Console UI | Console access | 4305 | |
| 26 | +| Caster API/UI | Infrastructure orchestration | 4310 | |
| 27 | +| Alloy API/UI | Advanced orchestration | 4403 | |
| 28 | +| TopoMojo API/UI | Network topology simulation | 5000/4201 | |
| 29 | +| Steamfitter API/UI | Scenario execution | 4401 | |
| 30 | +| CITE API/UI | Collaborative training | 4721 | |
| 31 | +| Gallery API/UI | Content management | 4723 | |
| 32 | +| Blueprint API/UI | Scenario design | 4725 | |
| 33 | +| Gameboard API/UI | Competition/scoring | 4202 | |
| 34 | +| Moodle | LMS integration | 8081 | |
| 35 | +| LRsql | Learning Record Store (xAPI) | 9274 | |
| 36 | + |
| 37 | +### Service Configuration |
| 38 | +Services are controlled via environment files in `.env/` directory and `LaunchOptions` class. Environment files use `Launch__<ServiceName>=true/false` pattern (e.g., `Launch__Player=true`). Each service can be individually toggled without rebuilding. |
| 39 | + |
| 40 | +## Common Commands |
| 41 | + |
| 42 | +### Building |
| 43 | +```bash |
| 44 | +dotnet build Crucible.slnx |
| 45 | +dotnet publish Crucible.slnx |
| 46 | +``` |
| 47 | + |
| 48 | +### Running Services |
| 49 | +Use VS Code's Run and Debug panel with launch configurations. Each configuration uses a corresponding `.env/<name>.env` file: |
| 50 | +- **Default** - All default services (excluding Moodle/LRsql) |
| 51 | +- **Exercise**, **TTX** - Specific service combinations |
| 52 | +- **Service-specific** - Player, Caster, Alloy, TopoMojo, Steamfitter, CITE, Gallery, Blueprint, Gameboard |
| 53 | +- **Moodle** - Runs Moodle without xdebug |
| 54 | +- **Moodle Debug** - Compound task that runs Moodle with xdebug enabled (starts both Moodle-Xdebug and Xdebug configurations) |
| 55 | +- **Lrsql** - Runs Learning Record Store |
| 56 | + |
| 57 | +### Database Operations |
| 58 | +```bash |
| 59 | +# Seed/restore database (example: blueprint) |
| 60 | +docker cp blueprint.dump crucible-postgres:/tmp/blueprint.dump |
| 61 | +docker exec -it crucible-postgres /bin/bash |
| 62 | +/usr/lib/postgresql/17/bin/psql --username=postgres blueprint < /tmp/blueprint.dump |
| 63 | + |
| 64 | +# Backup database |
| 65 | +docker exec -it crucible-postgres /bin/bash |
| 66 | +pg_dump -U postgres blueprint > /tmp/blueprint.dump |
| 67 | +exit |
| 68 | +docker cp crucible-postgres:/tmp/blueprint.dump blueprint.dump |
| 69 | +``` |
| 70 | + |
| 71 | +### Global Tools |
| 72 | +```bash |
| 73 | +dotnet tool install -g Aspire.Cli |
| 74 | +dotnet tool install --global dotnet-ef --version 10 |
| 75 | +npm install -g @angular/cli@latest |
| 76 | +``` |
| 77 | + |
| 78 | +## Development Patterns |
| 79 | + |
| 80 | +### Adding New Services |
| 81 | +1. Add repository to `scripts/repos.json` |
| 82 | +2. Update `Crucible.AppHost/AppHost.cs` with service registration |
| 83 | +3. Add launch configuration to `.vscode/launch.json` |
| 84 | +4. Create environment file in `.env/` directory |
| 85 | + |
| 86 | +### Adding Moodle Plugins |
| 87 | +1. Add repository to `scripts/repos.json` |
| 88 | +2. Update `.vscode/launch.json` (add path mappings for xdebug) |
| 89 | +3. Update `Crucible.AppHost/AppHost.cs` (add bind mounts) |
| 90 | +4. Update `scripts/xdebug_filter.sh` |
| 91 | +5. For additional paths: also update `Dockerfile.MoodleCustom`, `add-moodle-mounts.sh`, `pre_configure.sh` |
| 92 | + |
| 93 | +### Service Dependencies Pattern |
| 94 | +All services follow this pattern in `AppHost.cs`: |
| 95 | +- `.WaitFor(postgres)` - Wait for database |
| 96 | +- `.WaitFor(keycloak)` - Wait for identity provider |
| 97 | +- `.WithReference(db, "PostgreSQL")` - Database connection |
| 98 | +- `.WithExplicitStart()` - Service won't auto-start |
| 99 | + |
| 100 | +## Key Files |
| 101 | + |
| 102 | +- `Crucible.AppHost/AppHost.cs` - Main service orchestration logic |
| 103 | +- `Crucible.AppHost/LaunchOptions.cs` - Service toggle options |
| 104 | +- `Crucible.slnx` - Solution file including external projects |
| 105 | +- `scripts/repos.json` - List of repositories to clone |
| 106 | +- `scripts/clone-repos.sh` - Repository cloning script |
| 107 | +- `.env/*.env` - Environment configurations for different launch profiles |
| 108 | +- `Crucible.AppHost/resources/` - UI configuration files and Keycloak realm |
| 109 | + |
| 110 | +## Requirements |
| 111 | + |
| 112 | +### License Headers |
| 113 | +All source files require MIT (SEI)-style copyright headers. Enforced by GitHub Actions on PRs. |
| 114 | + |
| 115 | +```csharp |
| 116 | +// Copyright 2025 Carnegie Mellon University. All Rights Reserved. |
| 117 | +// Released under a MIT (SEI)-style license. See LICENSE.md in the project root for license information. |
| 118 | +``` |
| 119 | + |
| 120 | +### Docker Resources |
| 121 | +- Memory: 16GB minimum |
| 122 | +- Disk: 120GB minimum |
| 123 | + |
| 124 | +### Custom Certificates |
| 125 | +For corporate proxy environments (Zscaler), place certificates in `.devcontainer/certs/`. See `.devcontainer/certs/README.md`. |
| 126 | + |
| 127 | +## Moodle Development |
| 128 | + |
| 129 | +### OAuth Setup |
| 130 | +After first Moodle start: |
| 131 | +1. Login with oauth admin user to create account in Moodle |
| 132 | +2. Make oauth admin a site admin (either via local admin UI or restart Moodle container - it auto-adds oauth admin on restart) |
| 133 | +3. Login as oauth admin, go to Site Administration > Server > OAuth server settings and connect the system account |
| 134 | + |
| 135 | +### Xdebug |
| 136 | +- Control xdebug mode via `Launch__XdebugMode` in env files (values: `off`, `debug`, `coverage`, etc.) |
| 137 | +- **Warning**: PHP will pause execution after "Upgrading config.php..." if xdebug is enabled but VS Code debugger isn't running |
| 138 | +- Xdebug listens on port 9003; ensure the Xdebug launch config is running before starting Moodle with xdebug enabled |
| 139 | +- Debug display in browser: use `tool_userdebug` plugin icon (left of user avatar) |
| 140 | + |
| 141 | +### Plugin Configuration |
| 142 | +- **Crucible Plugin**: Requires oauth configured, service account connected, and user logged in via oauth |
| 143 | +- **TopoMojo Plugin**: Generate API key in TopoMojo UI and add to Moodle plugin config or `post_configure.sh` |
| 144 | +- **Additional Official Plugins**: Add to `PLUGINS` environment variable in `AppHost.cs` |
| 145 | + |
| 146 | +## Troubleshooting |
| 147 | + |
| 148 | +- **Aspire resources exit with no log**: Run `docker ps -a` to see stopped containers and error codes |
| 149 | +- **npm install issues on ARM**: May need additional OS packages; run `npm i` manually to see errors |
| 150 | +- **C# extension fails in container**: Reinstall extensions listed in `devcontainer.json` |
0 commit comments