Getting Started¶

Requirements¶

.NET 11 SDK (Preview)
Node.js 20+
Docker Desktop
OpenAI API Key - for AI features
GitHub Personal Access Token with read:packages scope — required to install @jankrajewskiit/ui from GitHub Packages

GitHub Packages Authentication¶

Both the frontend (@jankrajewskiit/ui via npm) and backend (Extensions.* via NuGet) depend on packages published to GitHub Packages. A single GHCR_TOKEN environment variable covers both.

Create a token¶

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token (classic)
Select scope: read:packages
Copy the generated token

Set the token locally¶

# Windows — persist for all future sessions (restart terminal after)
[System.Environment]::SetEnvironmentVariable("GHCR_TOKEN", "ghp_yourTokenHere", "User")

# Linux / macOS — add to ~/.bashrc or ~/.zshrc
export GHCR_TOKEN=ghp_yourTokenHere

After setting the variable, run npm install and dotnet restore normally. The token is read by recron-web/.npmrc and nuget.config — it is never committed to the repository.

CI/CD

In GitHub Actions the built-in GHCR_TOKEN secret is used automatically — no PAT needed in pipelines.

Running the Project¶

1. Clone the Repository¶

git clone https://github.com/jkrajewski/recron.git
cd recron

2. Run via Aspire¶

cd Recron.AppHost
dotnet run

Aspire automatically starts:

PostgreSQL with databases (organizer, questions, portfolio, users)
Keycloak (OIDC provider)
OpenAI integration (gpt-4o-mini)
All API services (Organizer, Questions, Portfolio, Users)
YARP API Gateway
Scalar API Reference
Frontend (recron-web)
Documentation (this site)

3. Available Endpoints¶

Service	URL
Aspire Dashboard	https://localhost:17014
Gateway	http://localhost:5000
Frontend	http://localhost:3000
Vite Dev Server	http://localhost:5173
Documentation	http://localhost:8081
Keycloak	https://auth.bluebraces.online
PgWeb	Available via Aspire Dashboard

Developer Commands¶

Backend¶

# Build all projects
dotnet build

# Database migrations
cd Questions.Api && dotnet ef migrations add <Name>
cd Questions.Api && dotnet ef database update

# Tests
dotnet test

Frontend¶

cd recron-web

# Install dependencies
npm install

# Development server
npm run dev

# Linting
npm run lint:fix

# Production build (includes typecheck)
npm run build

Troubleshooting¶

Ports Already in Use¶

If ports are occupied, check which processes are using them:

# Windows
netstat -ano | findstr :5000
netstat -ano | findstr :8080

# Linux/Mac
lsof -i :5000
lsof -i :8080

Docker Not Working¶

Make sure Docker Desktop is running and has access to sufficient resources.

Keycloak Issues¶

On first run, Keycloak may need a few minutes to initialize. Check the logs in Aspire Dashboard.