From nothing to a verified event in about 15 minutes. You need Docker with Compose, and a page you can edit (any local HTML file served over http://localhost works).
- 1
Start Trace (one command)
You need Docker. Then:
Terminalgit clone https://github.com/trace-id/trace.git cd trace ./setup.sh # Windows PowerShell: .\setup.ps1That's all. The script creates
docker/.envwith random secrets the first time (and keeps it afterwards), starts the database, Redis, the server and the dashboard, waits until they are ready, and prints:TextTrace is running. Dashboard: http://localhost:3000 API: http://localhost:8080The first start builds the images and takes a few minutes; later starts take seconds. Stop with
docker compose -f docker/compose.yml down.Ports in use?
Set
SERVER_PORTorDASHBOARD_PORTindocker/.envand run the script again. If you change the dashboard's address, also setDASHBOARD_URLto exactly the URL you open in the browser.Without the script
Copy
docker/.env.exampletodocker/.env, setPOSTGRES_PASSWORD,TOKEN_SECRETandAUTH_SECRETto 32 or more random letters and digits each (for exampleopenssl rand -hex 32; avoid/and+, which break the database URL), then rundocker compose -f docker/compose.yml up --build -d. - 2
Create your account and keys (3 minutes)
- Open
http://localhost:3000and choose Create an account. The first account becomes the administrator; further sign-ups are closed unless you enable them. - Create a project.
- On Keys, create a public key. Under allowed origins, enter the origin of the page that will load the SDK, for example
http://localhost:5500. Copy thepk_...key. - Create a secret key and copy the
sk_...key. Both are shown only once.
- Open
- 3
Add the SDK to a page (3 minutes)
The server hosts the browser SDK itself. Add this to your page and replace the key:
HTML<button id="go">Identify</button> <pre id="out"></pre> <script type="module"> import { createClient } from 'http://localhost:8080/sdk/sdk.esm.js'; const client = createClient({ apiKey: 'pk_REPLACE_ME', endpoint: 'http://localhost:8080' }); document.getElementById('go').onclick = async () => { const result = await client.get({ linkedId: 'test-user' }); document.getElementById('out').textContent = JSON.stringify(result, null, 2); }; </script>Serve the page from the origin you allowed (for example
npx serve -l 5500in its folder) and click Identify. You get aneventIdand avisitorId. Open the page in a private window and click again: thevisitorIdshould match.Origin not allowed?
The page's origin must match an allowed origin on the public key exactly, including the port.
file://pages have no usable origin; serve the page overhttp://localhost. - 4
Verify on your backend (2 minutes)
Never trust the result in the browser. Send the
eventIdto your server and fetch the verified event with the secret key:Terminalcurl -H "Authorization: Bearer sk_REPLACE_ME" http://localhost:8080/v1/events/EVENT_IDOr from Node 18+:
JavaScriptconst res = await fetch(`http://localhost:8080/v1/events/${eventId}`, { headers: { Authorization: `Bearer ${process.env.SECRET_KEY}` }, signal: AbortSignal.timeout(2000), }); const event = await res.json(); // visitorId, suspectScore, reasons, signals, ...Events can be verified for 60 minutes. The response explains the score in
reasons. - 5
Look around (2 minutes)
Back in the dashboard, Overview shows the events per day, Events lets you search by
linkedId, visitor or score, and each event page explains its score signal by signal.
Next steps
- Decide what happens when the service is slow or down: fail open or fail closed.
- Use the React SDK or install the SDKs from npm.
- Before going live: TLS,
TRUST_PROXY, backups and IP data in the self-hosting guide. - Receive signed webhooks instead of polling.