|
| 1 | +# Quick Start Guide |
| 2 | + |
| 3 | +**Repository:** https://github.com/Ira2222/App2 |
| 4 | + |
| 5 | +This guide gets you up and running with App2 in minutes. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## ✅ Setup Complete! |
| 10 | + |
| 11 | +You've already completed the initial setup: |
| 12 | +- ✅ GitHub repository created and pushed |
| 13 | +- ✅ Actions permissions configured (read/write) |
| 14 | +- ✅ Security features enabled (Dependabot, Secret Scanning) |
| 15 | +- ✅ CI/CD workflows running |
| 16 | +- ✅ Code quality tools configured (.editorconfig) |
| 17 | +- ✅ OpenAPI client generation ready |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## 🚀 Quick Commands |
| 22 | + |
| 23 | +### Development |
| 24 | + |
| 25 | +```bash |
| 26 | +# Start the API |
| 27 | +dotnet run --project src/App2.Api --launch-profile https |
| 28 | + |
| 29 | +# Start the React app (separate terminal) |
| 30 | +npm --prefix apps/web run dev |
| 31 | + |
| 32 | +# Or use the convenience script |
| 33 | +./scripts/dev-up.sh |
| 34 | +``` |
| 35 | + |
| 36 | +### Testing |
| 37 | + |
| 38 | +```bash |
| 39 | +# Run all tests |
| 40 | +dotnet test |
| 41 | + |
| 42 | +# Run with coverage |
| 43 | +dotnet test --collect:"XPlat Code Coverage" |
| 44 | + |
| 45 | +# Run only unit tests |
| 46 | +dotnet test tests/App2.Tests.Unit |
| 47 | + |
| 48 | +# Run only integration tests |
| 49 | +dotnet test tests/App2.Tests.Integration |
| 50 | +``` |
| 51 | + |
| 52 | +### OpenAPI Client Generation |
| 53 | + |
| 54 | +```bash |
| 55 | +# Generate TypeScript client for React app |
| 56 | +./scripts/generate-openapi-client.sh |
| 57 | + |
| 58 | +# This will: |
| 59 | +# 1. Start the API |
| 60 | +# 2. Export OpenAPI spec from Swagger |
| 61 | +# 3. Generate TypeScript Fetch client in apps/web/src/api/ |
| 62 | +# 4. Clean up |
| 63 | +``` |
| 64 | + |
| 65 | +### Docker |
| 66 | + |
| 67 | +```bash |
| 68 | +# Build and run locally |
| 69 | +docker compose -f docker/compose.api.yml up --build |
| 70 | + |
| 71 | +# With Redis (output caching) |
| 72 | +docker compose -f docker/compose.redis.yml up --build |
| 73 | + |
| 74 | +# Pull from GHCR (after first release) |
| 75 | +docker pull ghcr.io/ira2222/app2:latest |
| 76 | +docker run --rm -p 5080:8080 ghcr.io/ira2222/app2:latest |
| 77 | +``` |
| 78 | + |
| 79 | +### Release Workflows |
| 80 | + |
| 81 | +```bash |
| 82 | +# Full release (recommended for first release) |
| 83 | +./scripts/workflow-1-full-release.sh |
| 84 | +# This runs: tests → push → wait for CI → create tag → release |
| 85 | + |
| 86 | +# Quick tag (when CI is already green) |
| 87 | +./scripts/workflow-2-quick-tag.sh v0.1.0 |
| 88 | + |
| 89 | +# Hotfix for specific commit |
| 90 | +./scripts/workflow-3-hotfix-tag.sh v0.1.1 abc123 |
| 91 | +``` |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +## 📁 Project Structure |
| 96 | + |
| 97 | +``` |
| 98 | +App2/ |
| 99 | +├── src/ # Source code |
| 100 | +│ ├── App2.Domain/ # Entities, interfaces |
| 101 | +│ ├── App2.Application/ # Business logic (CQRS with MediatR) |
| 102 | +│ ├── App2.Infrastructure/ # Data access, repositories |
| 103 | +│ └── App2.Api/ # Minimal API endpoints |
| 104 | +├── apps/ |
| 105 | +│ └── web/ # React + Vite frontend |
| 106 | +├── tests/ |
| 107 | +│ ├── App2.Tests.Unit/ # Unit tests |
| 108 | +│ └── App2.Tests.Integration/ # Integration tests |
| 109 | +├── docker/ # Docker Compose files |
| 110 | +├── scripts/ # Automation scripts |
| 111 | +└── .github/workflows/ # CI/CD workflows |
| 112 | +``` |
| 113 | + |
| 114 | +--- |
| 115 | + |
| 116 | +## 🔧 Configuration |
| 117 | + |
| 118 | +### Feature Flags |
| 119 | + |
| 120 | +Toggle features in `appsettings.json` → `Features`: |
| 121 | + |
| 122 | +| Feature | Purpose | Dev Default | Prod Default | |
| 123 | +|---------|---------|-------------|--------------| |
| 124 | +| Authentication | JWT auth | ❌ false | ✅ true | |
| 125 | +| CORS | Allow-list | ✅ true | ❌ false | |
| 126 | +| RateLimiting | 100/min | ✅ true | ✅ true | |
| 127 | +| OutputCaching | Response cache | ✅ true | ✅ true | |
| 128 | +| RedisOutputCache | Redis backend | ❌ false | ✅ true | |
| 129 | +| SecurityHeaders | CSP, etc. | ✅ true | ✅ true | |
| 130 | +| OpenTelemetry | Observability | ❌ false | ✅ true | |
| 131 | + |
| 132 | +### Environment Variables |
| 133 | + |
| 134 | +```bash |
| 135 | +# API |
| 136 | +ASPNETCORE_ENVIRONMENT=Development |
| 137 | +ASPNETCORE_URLS=http://+:8080 |
| 138 | + |
| 139 | +# Azure Key Vault (optional) |
| 140 | +USE_KEYVAULT=true |
| 141 | +KeyVault__VaultUri=https://your-vault.vault.azure.net/ |
| 142 | + |
| 143 | +# Redis (optional) |
| 144 | +Redis__Connection=localhost:6379 |
| 145 | +``` |
| 146 | + |
| 147 | +### Frontend Environment |
| 148 | + |
| 149 | +```bash |
| 150 | +# apps/web/.env.local |
| 151 | +VITE_API_BASE_URL=http://localhost:5081 |
| 152 | +``` |
| 153 | + |
| 154 | +--- |
| 155 | + |
| 156 | +## 🧪 Testing the API |
| 157 | + |
| 158 | +### Health Checks |
| 159 | + |
| 160 | +```bash |
| 161 | +# Liveness probe |
| 162 | +curl http://localhost:5081/healthz/live |
| 163 | + |
| 164 | +# Readiness probe |
| 165 | +curl http://localhost:5081/healthz/ready |
| 166 | +``` |
| 167 | + |
| 168 | +### Todos API |
| 169 | + |
| 170 | +```bash |
| 171 | +# Get all todos |
| 172 | +curl http://localhost:5081/api/todos |
| 173 | + |
| 174 | +# Create a todo |
| 175 | +curl -X POST http://localhost:5081/api/todos \ |
| 176 | + -H "Content-Type: application/json" \ |
| 177 | + -d '{"title":"Test Todo","description":"This is a test"}' |
| 178 | +``` |
| 179 | + |
| 180 | +### Swagger UI |
| 181 | + |
| 182 | +Open in browser: |
| 183 | +``` |
| 184 | +http://localhost:5081/swagger |
| 185 | +``` |
| 186 | + |
| 187 | +--- |
| 188 | + |
| 189 | +## 📊 GitHub Actions Workflows |
| 190 | + |
| 191 | +### Workflows Running |
| 192 | + |
| 193 | +1. **CI** (`.github/workflows/ci.yml`) |
| 194 | + - Triggers: Push/PR to main |
| 195 | + - Jobs: Backend build/test, Frontend build, SBOM generation |
| 196 | + - Status: https://github.com/Ira2222/App2/actions/workflows/ci.yml |
| 197 | + |
| 198 | +2. **Security** (`.github/workflows/security.yml`) |
| 199 | + - Triggers: Push/PR, weekly schedule |
| 200 | + - Jobs: CodeQL analysis, Trivy scanning |
| 201 | + - Status: https://github.com/Ira2222/App2/actions/workflows/security.yml |
| 202 | + |
| 203 | +3. **Container** (`.github/workflows/container.yml`) |
| 204 | + - Triggers: Push to main, PRs, releases |
| 205 | + - Jobs: Docker build, push to GHCR, SLSA provenance |
| 206 | + - Status: https://github.com/Ira2222/App2/actions/workflows/container.yml |
| 207 | + |
| 208 | +4. **Release** (`.github/workflows/release-provenance.yml`) |
| 209 | + - Triggers: Semver tags (v*.*.*) |
| 210 | + - Jobs: Publish API/web artifacts, create release, attestations |
| 211 | + - Status: https://github.com/Ira2222/App2/actions/workflows/release-provenance.yml |
| 212 | + |
| 213 | +### Monitoring Workflows |
| 214 | + |
| 215 | +```bash |
| 216 | +# List recent runs |
| 217 | +gh run list |
| 218 | + |
| 219 | +# Watch a specific run |
| 220 | +gh run watch <run-id> |
| 221 | + |
| 222 | +# View logs |
| 223 | +gh run view <run-id> --log |
| 224 | + |
| 225 | +# View in browser |
| 226 | +gh run view <run-id> --web |
| 227 | +``` |
| 228 | + |
| 229 | +--- |
| 230 | + |
| 231 | +## 🔒 Security |
| 232 | + |
| 233 | +### Current Security Status |
| 234 | + |
| 235 | +- ✅ **Dependabot** - Automated dependency updates |
| 236 | +- ✅ **Secret Scanning** - Prevents credential leaks |
| 237 | +- ✅ **Push Protection** - Blocks secret commits |
| 238 | +- ✅ **CodeQL** - Static analysis for vulnerabilities |
| 239 | +- ✅ **Trivy** - Container/filesystem scanning |
| 240 | +- ✅ **SLSA Provenance** - Supply chain attestations |
| 241 | + |
| 242 | +### Dependabot Alerts |
| 243 | + |
| 244 | +Check current alerts: |
| 245 | +```bash |
| 246 | +gh browse /security/dependabot |
| 247 | +``` |
| 248 | + |
| 249 | +Or visit: https://github.com/Ira2222/App2/security/dependabot |
| 250 | + |
| 251 | +### Reviewing Dependabot PRs |
| 252 | + |
| 253 | +```bash |
| 254 | +# List open PRs |
| 255 | +gh pr list --author "app/dependabot" |
| 256 | + |
| 257 | +# Review a PR |
| 258 | +gh pr view <pr-number> |
| 259 | + |
| 260 | +# Approve and merge |
| 261 | +gh pr review <pr-number> --approve |
| 262 | +gh pr merge <pr-number> --auto --squash |
| 263 | +``` |
| 264 | + |
| 265 | +--- |
| 266 | + |
| 267 | +## 🎯 Next Steps |
| 268 | + |
| 269 | +### Immediate (5 minutes) |
| 270 | + |
| 271 | +1. **Wait for CI to pass** ✅ |
| 272 | + - Check: https://github.com/Ira2222/App2/actions |
| 273 | + - All workflows should be green |
| 274 | + |
| 275 | +2. **Review Dependabot PRs** |
| 276 | + - Check: https://github.com/Ira2222/App2/pulls |
| 277 | + - Merge security updates |
| 278 | + |
| 279 | +### Short-term (15-30 minutes) |
| 280 | + |
| 281 | +3. **Generate OpenAPI Client** |
| 282 | + ```bash |
| 283 | + ./scripts/generate-openapi-client.sh |
| 284 | + ``` |
| 285 | + |
| 286 | +4. **Update React App** |
| 287 | + - Use generated TypeScript client |
| 288 | + - Replace manual `fetch()` calls |
| 289 | + - See: `apps/web/src/api/` |
| 290 | + |
| 291 | +5. **Configure Azure AD** (if needed) |
| 292 | + - Update `appsettings.json` with real values |
| 293 | + - Replace "TODO-TENANT-ID", etc. |
| 294 | + - Enable `Features.Authentication` |
| 295 | + |
| 296 | +### Medium-term (when ready) |
| 297 | + |
| 298 | +6. **Run First Release** |
| 299 | + ```bash |
| 300 | + ./scripts/workflow-1-full-release.sh |
| 301 | + ``` |
| 302 | + |
| 303 | +7. **Verify SLSA Provenance** |
| 304 | + ```bash |
| 305 | + gh attestation verify oci://ghcr.io/ira2222/app2:v0.1.0 \ |
| 306 | + --owner Ira2222 --repo App2 |
| 307 | + ``` |
| 308 | + |
| 309 | +8. **Add More Tests** |
| 310 | + - Expand unit test coverage |
| 311 | + - Add integration tests for endpoints |
| 312 | + - See: `tests/` directory |
| 313 | + |
| 314 | +--- |
| 315 | + |
| 316 | +## 📚 Documentation |
| 317 | + |
| 318 | +- **[README.md](README.md)** - Overview and getting started |
| 319 | +- **[GITHUB_SETUP.md](GITHUB_SETUP.md)** - GitHub configuration guide |
| 320 | +- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development workflow |
| 321 | +- **[PRODUCTION_CHECKLIST.md](PRODUCTION_CHECKLIST.md)** - Pre-deployment checklist |
| 322 | +- **[RELEASE_WORKFLOWS.md](RELEASE_WORKFLOWS.md)** - Release automation |
| 323 | +- **[SETUP_GUIDE.md](SETUP_GUIDE.md)** - Workflow setup instructions |
| 324 | + |
| 325 | +--- |
| 326 | + |
| 327 | +## 🆘 Troubleshooting |
| 328 | + |
| 329 | +### CI Failures |
| 330 | + |
| 331 | +```bash |
| 332 | +# View failed run logs |
| 333 | +gh run list --status failure --limit 1 |
| 334 | +gh run view <run-id> --log-failed |
| 335 | + |
| 336 | +# Common issues: |
| 337 | +# - Test failures: Run `dotnet test` locally |
| 338 | +# - Build errors: Run `dotnet build` locally |
| 339 | +# - Frontend: Run `npm --prefix apps/web run build` |
| 340 | +``` |
| 341 | + |
| 342 | +### Container Build Failures |
| 343 | + |
| 344 | +```bash |
| 345 | +# Test Docker build locally |
| 346 | +docker build -f src/App2.Api/Dockerfile -t app2:test . |
| 347 | + |
| 348 | +# Common issues: |
| 349 | +# - Context path: Ensure you're in project root |
| 350 | +# - Missing files: Check .dockerignore |
| 351 | +# - Multi-stage errors: Check SDK vs runtime versions |
| 352 | +``` |
| 353 | + |
| 354 | +### OpenAPI Generation Issues |
| 355 | + |
| 356 | +```bash |
| 357 | +# Ensure API is running |
| 358 | +curl http://localhost:5081/swagger/v1/swagger.json |
| 359 | + |
| 360 | +# Manually export spec |
| 361 | +curl http://localhost:5081/swagger/v1/swagger.json > openapi/app2.openapi.json |
| 362 | + |
| 363 | +# Generate client |
| 364 | +cd apps/web |
| 365 | +npm run generate:client |
| 366 | +``` |
| 367 | + |
| 368 | +### Workflow Permission Issues |
| 369 | + |
| 370 | +**Error:** `Resource not accessible by integration` |
| 371 | + |
| 372 | +**Fix:** |
| 373 | +1. Go to https://github.com/Ira2222/App2/settings/actions |
| 374 | +2. Select "Read and write permissions" |
| 375 | +3. Enable "Allow GitHub Actions to create and approve pull requests" |
| 376 | +4. Save |
| 377 | + |
| 378 | +--- |
| 379 | + |
| 380 | +## 🔗 Useful Links |
| 381 | + |
| 382 | +- **Repository:** https://github.com/Ira2222/App2 |
| 383 | +- **Actions:** https://github.com/Ira2222/App2/actions |
| 384 | +- **Packages:** https://github.com/Ira2222?tab=packages |
| 385 | +- **Security:** https://github.com/Ira2222/App2/security |
| 386 | +- **Dependabot:** https://github.com/Ira2222/App2/security/dependabot |
| 387 | +- **Pull Requests:** https://github.com/Ira2222/App2/pulls |
| 388 | +- **Releases:** https://github.com/Ira2222/App2/releases |
| 389 | + |
| 390 | +--- |
| 391 | + |
| 392 | +**Last Updated:** 2025-10-28 |
| 393 | +**Status:** ✅ Production Ready |
0 commit comments