Skip to main content
Docs

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 20+ - Install Node.js
  • pnpm - npm install -g pnpm
  • Docker - For PostgreSQL and Redis
  • 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​

ServiceURLDescription
APIhttp://localhost:3000Rust API server
Swagger UIhttp://localhost:3000/v1/swagger-ui/API documentation
GraphiQLhttp://localhost:3000/v1/graphiqlGraphQL playground
Consolehttp://localhost:3001Admin dashboard
Heimdall IDhttp://localhost:3002Identity service
Docshttp://localhost:3003Documentation
Policieshttp://localhost:3004Legal & privacy policies
PostgreSQLlocalhost:5432Primary database
TimescaleDBlocalhost:5433Time-series GPS data
Redislocalhost:6379Cache & sessions
MailDevhttp://localhost:1080Email testing
MinIO S3http://localhost:9000Object storage
MinIO Consolehttp://localhost:9001Object storage console

5. Make Your First Request​

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

# Response: {"status":"ok","version":"2026.6.9"}

Development Commands​

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

Service Commands​

CommandDescription
just watch-apiRun API with hot reload
just watch-backendRun admin dashboard with hot reload
just watch-idRun identity service with hot reload
just watch-policiesRun policies site with hot reload
just watch-docsRun documentation with hot reload
just watch-dc-botRun Discord bot with hot reload
just watch-tw-botRun Twitch bot with hot reload
just stack-upStart PostgreSQL, TimescaleDB, Redis, MailDev, MinIO
just stack-downStop dev stack services

Database Commands​

CommandDescription
just migrateRun pending migrations
just migrate-downRollback last migration
just migrate-resetRollback all and re-run migrations
just migrate-statusShow migration status
just db-freshDrop, create, and migrate database

Schema Commands​

CommandDescription
just schemasGenerate OpenAPI and GraphQL schemas
just openapiGenerate OpenAPI spec only
just graphqlGenerate GraphQL schema only
just protoGenerate Protobuf Rust code

Testing Commands​

CommandDescription
just testRun all unit tests
just test-allRun ALL tests (unit + E2E)
just test-quickFast tests only (Rust + shared libs)
just test-apiAPI tests
just test-sharedAll shared library tests
just test-helpShow all test commands

Utility Commands​

CommandDescription
just initCopy example config files
just doctorCheck required tools are installed
just verify-apiFormat, lint, check API
just psqlOpen PostgreSQL shell
just redisOpen 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 (Rust)
│   ├── youtube_bot/      # YouTube bot (Rust)
│   └── 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​

Copy the example config and adjust as needed:

cp platform/api/config/default.toml.example platform/api/config/default.toml

Key configuration options:

[server]
host = "0.0.0.0"
port = 3000

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

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

Environment Variables​

Each Next.js app requires environment variables. Copy the examples:

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
cp platform/docs/.env.example platform/docs/.env.local

Docker Deployment​

Build and run with Docker:

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

# The Rust API image is built via Bazel (rules_img), not a Dockerfile:
#   bazel run //platform/api:api_push

# Run containers
docker run -p 3000:3000 heimdall-api
docker run -p 3001:3001 heimdall-backend
docker run -p 3002:3002 heimdall-id
docker run -p 3003:3003 heimdall-docs
docker run -p 3004:3004 heimdall-policies

Next Steps​

Now that you have Heimdall running:

API & Backend​

Shared Libraries​

Bots & Integrations​

Development​