Quick Start

Get up and running with Heimdall in minutes.

Prerequisites

Before you begin, make sure you have the following installed:

Rust (latest stable) - Install Rust
Node.js 24+ - Install Node.js
pnpm 10+ - npm install -g pnpm
Docker - For PostgreSQL, TimescaleDB, Redis, MailDev, MinIO
just - Command runner: cargo install just

1. Clone & Setup

# Clone the repository
git clone https://github.com/smutjebot/heimdall.git
cd heimdall

# Initialize config files
just init

# Install dependencies
pnpm install

2. Start Services

# Start the dev stack (PostgreSQL, TimescaleDB, Redis, MailDev, MinIO)
just stack-up

# Run database migrations
just migrate

3. Start Development Servers

Open multiple terminal windows:

# Terminal 1: Start the Rust API
just watch-api

# Terminal 2: Start the admin dashboard
just watch-backend

# Terminal 3: Start the identity service
just watch-id

# Terminal 4: Start the policies site (optional)
just watch-policies

# Terminal 5: Start the documentation (optional)
just watch-docs

4. Verify Installation

Service	URL	Description
API	http://localhost:3000	Rust API server
Swagger UI	http://localhost:3000/v1/swagger-ui/	API documentation
GraphiQL	http://localhost:3000/v1/graphiql	GraphQL playground
Console	http://localhost:3001	Admin dashboard
Heimdall ID	http://localhost:3002	Identity service
Docs	http://localhost:3003	Documentation
Policies	http://localhost:3004	Legal & privacy policies
PostgreSQL	localhost:5432	Primary database
TimescaleDB	localhost:5433	Time-series GPS data
Redis	localhost:6379	Cache & pub/sub
MailDev	http://localhost:1080	Email testing
MinIO S3	http://localhost:9000	Object storage
MinIO Console	http://localhost:9001	Object storage console

5. Make Your First Request

# Check API health
curl http://localhost:3000/health

Returns 200 when every dependency is reachable, 503 otherwise:

{
  "status": "healthy",
  "version": "2026.7.8",
  "timestamp": "2026-07-10T09:12:44.318+00:00",
  "uptime": { "days": 0, "hours": 0, "minutes": 3, "seconds": 12, "total": 192.0 },
  "services": {
    "database": { "status": "up", "responseTime": 2 },
    "timescaledb": { "status": "up", "responseTime": 3 },
    "redis": { "status": "up", "responseTime": 1 },
    "websocket": { "status": "up", "connections": 0, "subscriptions": 0 }
  },
  "apps": {
    "bots": {
      "discord_bot": { "status": "up", "responseTime": 4, "uptimeSeconds": 3600 }
    }
  },
  "_links": { "self": "http://localhost:3000/health" }
}

status is healthy or unhealthy. Bot entries are omitted when the bot is not configured.

Development Commands

Heimdall uses just as a command runner. Run just to see all available commands.

Service Commands

Command	Description
`just watch-api`	Run API with hot reload
`just watch-backend`	Run admin dashboard with hot reload
`just watch-id`	Run identity service with hot reload
`just watch-policies`	Run policies site with hot reload
`just watch-docs`	Run documentation with hot reload
`just watch-dc-bot`	Run Discord bot with hot reload
`just watch-tw-bot`	Run Twitch bot with hot reload (scaffold only)
`just stack-up`	Start PostgreSQL, TimescaleDB, Redis, MailDev, MinIO
`just stack-down`	Stop dev stack services

Database Commands

Command	Description
`just migrate`	Run pending migrations
`just migrate-down`	Rollback last migration
`just migrate-reset`	Rollback all and re-run migrations
`just migrate-status`	Show migration status
`just db-fresh`	Drop, create, and migrate database

Schema Commands

Command	Description
`just schemas`	Generate OpenAPI and GraphQL schemas
`just openapi`	Generate OpenAPI spec only
`just graphql`	Generate GraphQL schema only
`just proto`	Generate Protobuf Rust code

Testing Commands

Command	Description
`just test`	Run all unit tests
`just test-all`	Run ALL tests (unit + E2E)
`just test-quick`	Fast tests only (Rust + shared libs)
`just test-api`	API tests
`just test-shared`	All shared library tests
`just test-help`	Show all test commands

Utility Commands

Command	Description
`just init`	Copy example config files
`just doctor`	Check required tools are installed
`just verify-api`	Format, lint, check API
`just psql`	Open PostgreSQL shell
`just redis`	Open Redis shell

Project Structure

heimdall/
├── platform/
│   ├── api/              # Rust API backend
│   ├── backend/          # Admin dashboard (Next.js)
│   ├── id/               # Identity service (Next.js)
│   ├── docs/             # Documentation (Docusaurus)
│   ├── policies/         # Legal & privacy policies (Next.js)
│   ├── discord_bot/      # Discord bot (Rust/Poise)
│   ├── twitch_bot/       # Twitch bot — scaffold, not implemented
│   ├── youtube_bot/      # YouTube bot — scaffold, not implemented
│   └── proto/            # Shared Protobuf definitions
├── crates/               # 19 heimdall-* Rust crates (migrations live in heimdall-db/migrations)
│   ├── heimdall-api/         # HTTP server assembly
│   ├── heimdall-audit/       # Audit event types
│   ├── heimdall-audit-logger/# Audit logging
│   ├── heimdall-auth/        # Authentication & sessions
│   ├── heimdall-cache/       # Redis caching
│   ├── heimdall-common/      # Shared utilities
│   ├── heimdall-config/      # Configuration loading
│   ├── heimdall-db/          # Database & migrations
│   ├── heimdall-email/       # Email templates & sending
│   ├── heimdall-geoip/       # GeoIP lookups
│   ├── heimdall-graphql/     # GraphQL schema & resolvers
│   ├── heimdall-integrations/# Bot/service integrations
│   ├── heimdall-pegelonline/ # Pegelonline water-level API
│   ├── heimdall-proto/       # Protobuf definitions
│   ├── heimdall-rest/        # REST handlers
│   ├── heimdall-scheduler/   # Background jobs
│   ├── heimdall-storage/     # S3-compatible storage
│   ├── heimdall-telemetry/   # Tracing & metrics
│   └── heimdall-websocket/   # WebSocket (protobuf) server
├── shared/
│   ├── api/              # API client library (@elcto/api)
│   ├── ui/               # UI component library (@elcto/ui)
│   ├── cookies-consent/  # Cookie consent (@elcto/cookies-consent)
│   ├── player/           # Video player (@elcto/player)
│   └── test-utils/       # Test mocks & helpers (@elcto/test-utils)
├── docker/               # Dockerfiles
├── dev-stack/            # Docker Compose for dev
├── justfile              # Command runner
├── pnpm-workspace.yaml   # pnpm monorepo config
└── Cargo.toml            # Rust workspace

Configuration

API Configuration

platform/api/config/default.toml ships with the repository — do not edit it for local work. Put machine-specific overrides in platform/api/config/local.toml, which is gitignored and layered on top of the defaults:

[server]
host = "0.0.0.0"
port = 3000

[database]
url = "postgresql://postgres:postgres@localhost:5432/heimdall"

[redis]
url = "redis://localhost:6379"

Any value can also be overridden by environment variable using the double-underscore prefix, e.g. HEIMDALL__SERVER__PORT=3010.

Environment Variables

The Next.js apps read their configuration from env files. just init creates .env.local for the backend, id, and policies apps from their checked-in .env.example templates, and never overwrites an existing file. To do it by hand:

cp platform/backend/.env.example platform/backend/.env.local
cp platform/id/.env.example platform/id/.env.local
cp platform/policies/.env.example platform/policies/.env.local

The docs site needs no env file.

Docker Deployment

Build and run with Docker:

# Build the Next.js app images (Dockerfiles live in docker/) — or run `just docker-build`
docker build -f docker/backend.Dockerfile -t heimdall-backend .
docker build -f docker/id.Dockerfile -t heimdall-id .
docker build -f docker/policies.Dockerfile -t heimdall-policies .

# The Rust API and bot images are built via Bazel (rules_img), not Dockerfiles:
#   just bazel-push-api
#   just bazel-push-discord-bot

# Run containers
docker run -p 3001:3001 heimdall-backend
docker run -p 3002:3002 heimdall-id
docker run -p 3004:3004 heimdall-policies

Next Steps

Now that you have Heimdall running:

API & Backend

API Overview - Learn about all available APIs
Authentication - Set up authentication
REST API Reference - Complete REST endpoint reference
GraphQL Guide - Learn to use the GraphQL API
WebSocket Guide - Real-time communication
Storage API - S3-compatible file storage

Shared Libraries

UI Library - 42 React components (Button, Card, Modal, etc.)
API Library - REST, GraphQL, WebSocket clients
Cookie Consent - GDPR-compliant consent management
Video Player - Shaka-based HLS/DASH/CMAF player with DRM and resume support

Bots & Integrations

Discord Bot - Discord bot development guide
Code Examples - Integration examples in multiple languages

Development

Testing Guide - Testing commands and best practices
Architecture - System architecture overview

Prerequisites​

1. Clone & Setup​

2. Start Services​

3. Start Development Servers​

4. Verify Installation​

5. Make Your First Request​

Development Commands​

Service Commands​

Database Commands​

Schema Commands​

Testing Commands​

Utility Commands​

Project Structure​

Configuration​

API Configuration​

Environment Variables​

Docker Deployment​

Next Steps​

API & Backend​

Shared Libraries​

Bots & Integrations​

Development​