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, Redis, MailDev)
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
MailDevhttp://localhost:1080Email testing

5. Make Your First Request​

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

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

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-discord-botRun Discord bot with hot reload
just watch-twitch-botRun Twitch bot with hot reload
just stack-upStart PostgreSQL, Redis, MailDev
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 generate-openapiGenerate OpenAPI spec only
just generate-schemaGenerate 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)
│   ├── migrations/       # Database migrations
│   └── proto/            # Shared Protobuf definitions
├── crates/
│   ├── audit/            # Shared audit event types (heimdall-audit)
│   ├── proto/            # Protobuf definitions (heimdall-proto)
│   └── storage/          # S3-compatible storage (heimdall-storage)
├── 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)
├── 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 images
docker build -f docker/api.Dockerfile -t heimdall-api .
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 .

# 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​