Development Pipeline

Quick Reference

Purpose	macOS/Linux	Windows
Build everything	make build	.\build.ps1 build
Build backend only	make build_backend	.\build.ps1 build_backend
Build frontend only	make build_frontend	.\build.ps1 build_frontend
Package for distribution	./build.sh package	.\build.ps1 package
Run everything (development)	make run	.\build.ps1 run
Run backend only	make run_backend	.\build.ps1 run_backend
Run frontend only	make run_frontend	.\build.ps1 run_frontend
Run all tests	make test	.\build.ps1 test
Run unit tests	make test_unit	.\build.ps1 test_unit
Clean build artifacts	make clean	.\build.ps1 clean
Lint code	make lint	.\build.ps1 lint

Useful Commands

This section provides a reference for the standard development commands. While the examples below use make for cross-platform simplicity, all commands map directly to the underlying build scripts for your OS:

• Make (Cross-platform): make <target>
• Bash (Linux/macOS): ./build.sh <target>
• PowerShell (Windows): .\build.ps1 <target>

Building

Build everything (backend + frontend + docs + samples, etc.):

make build

Build only the backend:

make build_backend

Build only the frontend:

make build_frontend

Build with test coverage instrumentation:

make build_with_coverage

This will run unit tests, build with coverage flags, run integration tests, and generate a combined coverage report.

Building without Consent Server

By default, the build process downloads and packages the default consent server. If you want to skip this step, use the WITHOUT_CONSENT flag:

Using Make (Cross-platform)

# Build and test bypassing consent
make build WITHOUT_CONSENT=true
make test_integration WITHOUT_CONSENT=true

Using Bash (Linux/macOS)

./build.sh build --without-consent

Using PowerShell (Windows)

.\build.ps1 build --without-consent

Using Docker

docker build --build-arg WITH_CONSENT=false -t thunder:latest .

note

If you build without the consent server, you must also disable it when running setup and starting the server, as the scripts default to WITH_CONSENT=true. Run setup and start with the appropriate flag for your platform:

Bash (Linux/macOS)

./setup.sh --without-consent
./start.sh --without-consent

PowerShell (Windows)

.\setup.ps1 --without-consent
.\start.ps1 --without-consent

Make

make run WITHOUT_CONSENT=true

Docker (environment variable)

docker run -e WITH_CONSENT=false thunder:latest

Running

Run everything (backend + frontend):

make run

This automatically sets up the complete development environment with backend, frontend apps, and seed data.

If you built the project without the consent server, you must also run it with the flag to avoid startup errors:

make run WITHOUT_CONSENT=true

Run only the backend:

make run_backend

Run only the frontend:

make run_frontend

Testing

Run all backend tests (unit + integration):

make test

Run unit tests only:

make test_unit

Run integration tests only:

make test_integration

Run a specific integration test:

make test_integration RUN="TestName"

Run tests for a specific package:

make test_integration PACKAGE="pkg/path"

Run frontend unit tests:

cd frontend && pnpm test

note

make test only runs backend tests. Frontend and E2E tests must be run separately.

Code Coverage Requirements:

• Minimum: at least 80% code coverage for new code
• Encouraged: 100% coverage

E2E Tests (Playwright)

cd tests/e2e
npm ci
npx playwright test

E2E test options:

Option	Command
All browsers	npx playwright test
Chromium only	npx playwright test --project=chromium
Accessibility tests only	npx playwright test --grep @accessibility
Watch in browser	npx playwright test --headed
Step through interactively	npx playwright test --debug

Linting

Lint backend code:

make lint_backend

This uses golangci-lint to check code quality and style.

Lint frontend code:

make lint_frontend

Lint both backend and frontend:

make lint

Generating Mocks

Thunder uses mockery to generate mocks for unit tests.

Generate mocks:

make mockery

This will generate mocks based on the configurations in:

• .mockery.public.yml - For public interfaces
• .mockery.private.yml - For private interfaces

Generated mocks are placed in backend/tests/mocks/.

warning

CI has a verify-mocks job that will fail your build if mocks are out of sync with the interfaces. Always run make mockery after changing any interface.

Other Commands

Clean build artifacts:

make clean

Build Docker images:

# Single-arch image with version tag
make docker-build

# Multi-arch image (amd64 + arm64)
make docker-build-multiarch

View all available commands:

make help

Advanced Setup (Manual Mode)

Click to expand - Manual Frontend Setup

For developers who want to run frontend components separately without using make run commands.

Installing Dependencies

1. Navigate to the Thunder frontend directory.

cd frontend

2. Install the dependencies using pnpm.

pnpm install

Building the Project

Execute the build command to compile the project. This will build all the necessary packages and applications.

pnpm build

Seed Data (Optional)

Note: This step is only necessary if you are running the backend server manually and have not yet set up the initial data.

If you have not already created the Console application and the default admin user, you can do so by running the following command:

THUNDER_API_BASE="https://localhost:8090" \
  backend/cmd/server/bootstrap/01-default-resources.sh \
  --console-redirect-uris "https://localhost:5191/console"

Setting up the Thunder Gate Application

1. Point the gate_client in deployment.yaml to the local Thunder Gate application.

   • If you are running make run, change the gate_client section in backend/cmd/server/repository/conf/deployment.yaml
   • If you are running the backend server manually, change the gate_client section in <THUNDER_HOME>/repository/conf/deployment.yaml

gate_client:
  port: 5190

2. Add the local development origin of the Thunder Gate application (https://localhost:5190) to the CORS allowed origins in <THUNDER_HOME>/repository/conf/deployment.yaml.

cors:
  allowed_origins:
    - "https://localhost:5190"

3. Run the Thunder Gate application.

cd frontend
pnpm --filter @thunder/gate dev

Setting up the Thunder Console Application

IMPORTANT: This section assumes that you have already created the Console application using the initial data setup script. If not, please refer to the Seed Data section above.

1. First, retrieve the application ID of the Console application from the Thunder server. This will be the application with the client_id CONSOLE.

curl -k -X GET "https://localhost:8090/applications"

2. Then, get the current Console application configuration:

curl -k -X GET "https://localhost:8090/applications/<console-application-id>"

Note: Replace <console-application-id> with the actual application ID (e.g., 6100bc91-ba99-4ce9-87dd-6d4d80178c38) obtained from the previous step. The -k flag allows curl to work with self-signed SSL certificates in development.

3. Copy the response from step 2 and update the redirectUris in the JSON object to include the local development URL (ex: https://localhost:5191/console). Locate the inboundAuthConfig > config section and modify the redirectUris array:

"redirectUris": [
  "https://localhost:8090/console",
  "https://localhost:5191/console"
]

4. Update the Console application with the modified configuration by passing the updated JSON directly:

curl -k -X PUT "https://localhost:8090/applications/<console-application-id>" \
  -H "Content-Type: application/json" \
  -d '<paste-the-modified-json-here>'

5. Add the local development origin of the console application (https://localhost:5191) to the CORS allowed origins in <THUNDER_HOME>/repository/conf/deployment.yaml.

cors:
  allowed_origins:
    - "https://localhost:5191"

6. Run the Thunder Console application.

pnpm --filter @thunder/console dev

This will run the Thunder Console application on https://localhost:5191/console.

Development Workflow

For area-specific coding standards, see the Backend Development and Frontend Development guides.

1. Make Your Changes

Follow coding guidelines and best practices:

• Backend: Review .github/instructions/ for package structure, services, data access, API handlers, and testing patterns
• Frontend: See .github/instructions/frontend.instructions.md
• Security: Avoid SQL injection, XSS, command injection, and OWASP top 10 vulnerabilities

Best practices:

• Keep changes focused on a single issue
• Use meaningful variable/function names
• Add comments for complex logic
• Maintain consistency with existing code

2. Test and Validate Your Changes

Before committing, ensure code quality and correctness:

Purpose	Command
Backend unit tests	make test_unit
Backend integration tests	make test_integration
Backend all tests	make test
Frontend unit tests	cd frontend && pnpm test
E2E tests (Playwright)	cd tests/e2e && npm ci && npx playwright test
Lint backend	make lint_backend
Lint frontend	make lint_frontend

Requirements:

• All tests must pass
• Code coverage: at least 80% (higher encouraged)
• No linting errors
• Unit tests for business logic
• Integration tests for API endpoints
• Test edge cases and error scenarios

3. Commit Your Changes

Use clear, descriptive commit messages:

git commit -m "Fix token refresh failing after 30 minutes

Fixes #123"

Best practices:

• Make atomic commits (one logical change per commit) — ideally one commit per PR
• Write commit messages that explain why, not just what
• Reference the issue number using Fixes #<number> or Closes #<number>

4. Push and Create PR

Push your changes to your forked repository:

git push origin <branch-name>

Then create a Pull Request to the thunder/main branch on GitHub:

1. Go to your fork on GitHub
2. Click "Compare & pull request"
3. Provide a clear, descriptive title (e.g., "Add TOTP-based MFA support")
4. Fill in the PR templates
5. Link to the related issue
6. Ensure all CI checks pass

5. Address Review Feedback

• Respond to reviewer comments promptly
• Keep commit history clean — rebase review fixes into the appropriate commit rather than adding separate "fix review comments" commits
• Push updates to the same branch
• Re-request review when ready

6. Merge

Once approved by maintainers and all checks pass, a maintainer will merge your PR.