heimdall

Quick Start Guide

Get Heimdall running in under 5 minutes!

Prerequisites

Installation Steps

1. Clone Repository

git clone https://github.com/fulgidus/heimdall.git
cd heimdall

2. Configure Environment

# Copy environment template
cp .env.example .env

# Optional: Edit .env if you want to customize settings
# The defaults work fine for local development

3. Start All Services

# Start infrastructure (PostgreSQL, RabbitMQ, Redis, MinIO, etc.)
docker-compose up -d

# Wait 30 seconds for services to initialize
# Then verify all services are healthy
make health-check

4. Access the Application

Frontend UI:

Service UIs:

Verify Installation

# Check all containers are running
docker-compose ps

# Check health status
make health-check

# View logs
docker-compose logs -f

Development Credentials

All services use default development credentials:

Service Username Password Port
PostgreSQL heimdall_user changeme 5432
RabbitMQ guest guest 5672
MinIO minioadmin minioadmin 9000
Redis (requires password) changeme 6379

⚠️ Security Warning: These credentials are for development only. Never use these in production!

Next Steps

Run Tests

# Backend tests
make test

# Frontend tests
cd frontend && pnpm test

# E2E tests (requires backend running)
cd frontend && pnpm test:e2e

Explore the System

  1. Dashboard: View WebSDR status and system health at http://localhost:3000
  2. WebSDRs: Check receiver status at http://localhost:3000/websdrs
  3. Recording Sessions: Create and manage sessions at http://localhost:3000/sessions
  4. Localization: View real-time localization results at http://localhost:3000/localization

Development Workflow

# Start development mode (hot-reload)
make dev

# Run linting
make lint

# Format code
make format

# View API documentation
open http://localhost:8000/docs  # FastAPI Swagger UI

Troubleshooting

Services Won’t Start

# Stop all containers
docker-compose down -v

# Clean up and restart
docker-compose up -d --build

Health Check Fails

# Check container logs
docker-compose logs <service-name>

# Restart specific service
docker-compose restart <service-name>

Port Conflicts

If you get port conflict errors:

# Check what's using the port
lsof -i :5432  # Replace 5432 with conflicting port

# Stop conflicting service or change port in .env

Common Issues

Issue Solution
“Cannot connect to Docker daemon” Start Docker Desktop or Docker service
“Port already in use” Stop conflicting service or change port in .env
“Health check timeout” Wait longer or check logs with docker-compose logs
“Permission denied” Run with sudo or add user to docker group

Getting Help

What’s Next?