Configure and Run

Build from Source

Building from source produces a distributable .zip file at THUNDER_ROOT/target/dist/.

Linux/macOS

make build

Windows

.\build.ps1 build

What this does:

• Compiles the Go backend binary
• Initializes SQLite databases (config, runtime, user)
• Builds the frontend React apps (Thunder Gate + Thunder Develop)
• Builds the documentation
• Builds sample apps

Configure the Server

Open backend/cmd/server/repository/conf/deployment.yaml in your favorite text editor and make the following changes:

Add CORS allowed origins:

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

tip

This configuration allows the Thunder Gate and Thunder Console applications to communicate with the backend server during development.

Configure the Gate client:

gate_client:
  port: 5190

tip

This configuration points the backend server to the local Thunder Gate application for authentication.

Run the Server

Option A: All-in-one (Backend + Frontend together)

Start the Thunder server and apps in development mode.

Linux/macOS

make run

Windows

.\build.ps1 run

note

This command will automatically set up your complete development environment:

What happens:

• Installs frontend dependencies and builds packages
• Starts the frontend development servers
• Generates TLS certificates (if missing)
• Initializes SQLite databases
• Starts the backend server
• Runs the bootstrap script which creates:
  • The Develop application with the correct redirect URIs
  • The default admin user (admin / admin)

Services that start:

• Backend server: https://localhost:8090
• Thunder Gate (Login/Register): https://localhost:5190/gate
• Thunder Develop (Admin Console): https://localhost:5191/develop

Option B: Separate terminals (for debugging independently)

Use this approach when you need to debug the backend and frontend independently.

Terminal 1 - Backend:

Linux/macOS

make run_backend

Windows

.\build.ps1 run_backend

Terminal 2 - Frontend:

Linux/macOS

make run_frontend

Windows

.\build.ps1 run_frontend

Terminal 3 - Seed the initial data (one-time only):

Linux/macOS

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

Windows

$env:THUNDER_SKIP_SECURITY = "true"
$env:THUNDER_API_BASE = "https://localhost:8090"
& backend\cmd\server\bootstrap\01-default-resources.ps1 `
--develop-redirect-uris "https://localhost:5191/develop"

This creates the Develop application and the default admin user (admin / admin). You only need to do this once — the data persists in the SQLite databases.

warning

Don't use ./setup.sh here. That script is designed for the packaged distribution zip and expects a compiled ./thunder binary at the project root. From source code, always use the bootstrap script directly as shown above, or use make run (Option A) which handles everything for you.

Setup and Data Seeding

Thunder provides two different data seeding paths, depending on how the system is initialized.

Command	Use Case	Seeded Data
make run	Source development	Default resources
./setup.sh	Deployment / release initialization	Default + sample resources

Development Seeding (make run)

For development environments, make run executes the backend/cmd/server/bootstrap/01-default-resources.sh bootstrap script, which seeds the core resources required to start the server and access the console:

• Default Organization Unit
• Default User Schema (Person)
• Admin user (admin / admin)
• System resource server with system actions and permissions
• Administrator role and role assignment
• DEVELOP application

Full Bootstrap (./setup.sh)

For release artifacts and deployment environments, ./setup.sh performs a one-time initialization:

1. Starts Thunder temporarily with THUNDER_SKIP_SECURITY=true
2. Waits until the server becomes ready (/health/readiness)
3. Executes all scripts in the ./bootstrap directory in filename order
4. Stops the temporary server after initialization is complete

Bootstrap Scripts:

• 01-default-resources.sh — Seeds the core identity resources (same as development seeding above)
• 02-sample-resources.sh — Seeds additional sample resources used for demos and sample integrations:
  • customers Organization Unit
  • Customer user type schema
  • Sample App application
  • React SDK Sample App application

The setup logs also print the sample application IDs, which can be used when configuring the sample applications.

In short:

• Use make run when running Thunder from source.
• Use ./setup.sh when initializing a fresh runtime environment with the full bootstrap data.

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 update 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.