Set Up the Sample

This page walks you through the quick path: get ThunderID running behind a public URL, import a pre-built bundle, and run the apps. Everything the walkthroughs need is created in one step.

Prefer to build the setup manually?

Skip the bundle import and follow Configure It Yourself instead.

Set Up Your Environment

1

Get ThunderID

Download and extract the ThunderID distribution — follow Get ThunderID for the steps.

Don't start the server yet — you need to point it at your public URL first.

2

Get a public HTTPS URL for ThunderID

The wallet scans QR codes that point at ThunderID, so it must be reachable over public HTTPS. Two options:

Option A — Tunnel a local instance (free, no infrastructure needed)

Use cloudflared or any HTTPS tunnel:

cloudflared tunnel --url https://localhost:8090 --no-tls-verify

The terminal prints a public URL such as https://<random>.trycloudflare.com.

Option B — Deploy to a server

Deploy ThunderID to any cloud or on-premise host where it is reachable over HTTPS. See Deployment Patterns for guidance.

---

Either way, note your base URL as <PUBLIC_URL> and the hostname without https:// as <PUBLIC_HOST> — used in the steps below.

3

Point ThunderID at the public URL

In the distribution's deployment.yaml, set:

server:
  public_url: "<PUBLIC_URL>"

gate_client:
  hostname: "<PUBLIC_HOST>"
  port: 443
  scheme: "https"
  path: "/gate"

Then update the Gate and Console frontend config files so the browser-side apps call the public URL instead of localhost. In apps/gate/config.js and apps/console/config.js, set:

server: {
  hostname: '<PUBLIC_HOST>',
  port: 443,
  http_only: false,
},

See Configuration for a full reference.

4

Configure the Server

Add the Wayfinder origin to the server-config cors section so the browser app can call ThunderID. Create or update config/resources/server_configs/cors.yaml:

name: cors
value:
  allowedOrigins:
    # ...existing entries...
    - "http://localhost:5173"

5

Start ThunderID

./start.sh --bootstrap-and-serve

ThunderID is now running and reachable at <PUBLIC_URL>.

6

Get the Wayfinder Sample

Download the latest Wayfinder sample distribution.

7

Import the Sample Bundle

1. Open the ThunderID Console at <PUBLIC_URL>/console.
2. On first sign-in, a welcome screen appears with an Open button. (Later, reach it from the user profile menu.)
3. Click Open and select thunderid-config/redirect/thunderid-config.yaml.
4. Select thunderid-config/redirect/thunderid.env for environment variables.
5. The Console imports the files and reports the resources created.

8

Run the Sample

From the extracted sample directory:

npm install
VITE_THUNDER_BASE_URL=<PUBLIC_URL> npm run dev

Wayfinder opens at http://localhost:5173 and the Skyline Lounge kiosk at http://localhost:8795.

9

Install a Wallet

Install Heidi or Lissi on your phone. Both are pre-registered in the bundle.

Walkthroughs

Pick a walkthrough to begin. Each one starts from the setup above.

Issue CredentialJohn adds his Wayfinder Sky Pass to a mobile wallet from his profile page.Go to Issue Credential →

Verify CredentialJohn presents the Sky Pass at the Skyline Lounge kiosk, which grants access by tier.Go to Verify Credential →

Going Deeper

• New to decentralized identity? See the Decentralized Identity overview.
• Ready for production? See the Production Deployment Guidelines.