Run Registry Atlas locally

Use this page to get the Atlas SPA and its fetch proxy running on your laptop so you can inspect a registry or explore the bundled demo fixtures.

When to use this

Use these steps when you want to:

Explore the bundled Registry Relay demo fixtures without a live registry.
Point Atlas at a Registry Relay or other DCAT-compliant registry metadata endpoint.
Verify a discovery report against a running Registry Relay instance.

Prerequisites

Node.js 22 or later and pnpm installed. If you use mise, mise install covers both.
Rust toolchain (cargo on PATH). The first pnpm dev compiles Rust components to WebAssembly; without Rust installed you will get a cargo not found error. Install Rust from rustup.rs.
Optional: a running Registry Relay instance if you want to inspect live metadata. The Registry Lab tutorial describes how to start the demo compose topology, which includes a Relay instance. Note that Atlas is run separately and is not in the Registry Lab compose topology at v0.1.

Steps

1. Clone the repository

git clone https://github.com/jeremi/registry-atlas.git
cd registry-atlas

2. Install dependencies

pnpm install

This installs Node dependencies and prepares the Rust WASM build prerequisites. The semantic-asset-discovery-wasm crate is compiled during the next step.

3. Start the development server

pnpm dev

pnpm dev builds the WASM artifacts from the Rust crates and then starts two processes concurrently:

The Vite dev server on http://127.0.0.1:5177.
The Express fetch proxy on http://127.0.0.1:3717.

Both processes must be running for Atlas to function. The first run compiles semantic-asset-discovery-wasm from Rust; expect several minutes on a cold machine. Subsequent runs use the Rust incremental cache and finish much faster.

If you want the proxy alone (for example, to drive it from another tool), run:

pnpm server

4. Verify the proxy is healthy

curl -s http://127.0.0.1:3717/api/health

Expected output:

{"ok": true, "status": "ok"}

Production build

pnpm dev is for local development. If you need a static production build (for example, to serve Atlas from a web server without running the Vite dev server), run:

pnpm build

This type-checks, compiles WASM, and emits a production bundle into dist/. Serve dist/ from any static file server alongside the proxy (pnpm server).

Verification

Open http://127.0.0.1:5177 in a browser.

The Atlas workspace loads with an empty URL field. To confirm that the WASM engine and bundled fixtures are working:

Select Bundled Registry Relay discovery from the curated demo fixtures in the top bar.
Confirm the Overview tab shows semantic assets, access methods, recognized metadata, and follow-up evidence.
Open the Registry tab and select a dataset. Confirm the detail pane shows access methods.
Open the Capabilities tab. Confirm the social protection demo shows farmer_status, disability_status, and school_attendance as candidate routes with evidence and review flags.
Open the Evidence tab. Confirm the recognized metadata and publisher-specific metadata appear in separate sections.

Troubleshooting

WASM build fails with “wasm-pack not found”

wasm-pack is installed by the build script. If it is not on PATH, the script at scripts/build-semantic-asset-discovery-wasm.mjs will download and run it. If the download fails, check your internet connection and proxy settings.

Proxy returns `private_network_blocked`

The proxy blocks private-network targets (RFC 1918 ranges, loopback) in production mode. For local development, NODE_ENV is not production by default, so pnpm dev starts the proxy with local access enabled. If you override NODE_ENV=production manually, set ATLAS_PROXY_ALLOW_LOCAL=1 to permit localhost targets.

Port conflict on 5177 or 3717

Vite and Express use fixed ports in v0.1. Stop any other process listening on those ports before running pnpm dev.

`pnpm dev` hangs after “Starting Rust build”

The first WASM compilation can take several minutes on a cold machine. Subsequent runs use the Rust incremental cache and finish faster. Wait for the Vite dev server banner before opening the browser.