Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Version 20.10 or higherInstall Docker

Docker Compose

Version 2.0 or higherInstall Docker Compose
No other dependencies are required - all services run in containers with automated setup.

​
Quick Start

Get Chronoverse up and running in 3 simple steps:
1

Clone the Repository

git clone https://github.com/hitesh22rana/chronoverse.git
cd chronoverse
2

Start the Development Environment

docker compose -f compose.dev.yaml up -d
This will start all services including:
  • PostgreSQL (transactional database)
  • ClickHouse (analytics database)
  • Redis (caching layer)
  • Kafka (message broker)
  • Meilisearch (search engine)
  • All microservices and workers
  • Dashboard and monitoring
3

Access the Dashboard

Once all services are healthy (this may take 1-2 minutes), open your browser:
http://localhost:3001
You can also access the Grafana monitoring dashboard:
http://localhost:3000

​
Verify Installation

Check that all services are running: 
docker compose -f compose.dev.yaml ps
You should see all services with status Up or healthy.
The first startup generates TLS certificates and runs database migrations automatically. Subsequent startups will be much faster.

​
What’s Running?

The development environment exposes the following ports:
ServicePortDescription
Dashboard3001Web UI for managing workflows and jobs
API Server8080REST API endpoint
Users Service50051gRPC service for user management
Workflows Service50052gRPC service for workflow management
Jobs Service50053gRPC service for job management
Notifications Service50054gRPC service for notifications
Analytics Service50055gRPC service for analytics
ServicePortDescription
PostgreSQL5432Primary database
ClickHouse9440Analytics database (TLS)
Redis6379Cache and pub/sub (TLS)
Kafka9094Message broker (SSL)
Meilisearch7700Search engine (HTTPS)
Grafana3000Observability dashboard

​
Test the API

Create your first workflow using the REST API: 
curl -X POST http://localhost:8080/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "health-check",
    "type": "HEARTBEAT",
    "schedule": 5,
    "config": {}
  }'
This creates a simple HEARTBEAT workflow that runs every 5 minutes.

​
Create a Container Workflow

For more complex tasks, create a CONTAINER workflow that runs a Docker image: 
curl -X POST http://localhost:8080/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "type": "CONTAINER",
    "schedule": 10,
    "config": {
      "image": "alpine:latest",
      "command": ["echo", "Hello from Chronoverse!"],
      "env": {
        "ENVIRONMENT": "development"
      }
    }
  }'

​
Monitor Job Execution

Stream job logs in real-time using Server-Sent Events: 
curl -N http://localhost:8080/workflows/{workflow_id}/jobs/{job_id}/events
Or view them in the dashboard for a better experience.

​
Environment Variables

The development environment comes with sensible defaults. Key configuration: 
# PostgreSQL
POSTGRES_HOST: postgres
POSTGRES_USER: primary
POSTGRES_PASSWORD: chronoverse
POSTGRES_DB: chronoverse
POSTGRES_TLS_ENABLED: true

# ClickHouse
CLICKHOUSE_HOSTS: clickhouse:9440
CLICKHOUSE_USERNAME: chronoverse-client
CLICKHOUSE_PASSWORD: chronoverse
CLICKHOUSE_TLS_ENABLED: true

# Kafka
KAFKA_BROKERS: kafka:9094
KAFKA_TLS_ENABLED: true
KAFKA_CONSUMER_GROUP: workflow-worker

# Redis
REDIS_HOST: redis
REDIS_TLS_ENABLED: true

# Server
SERVER_HOST: 0.0.0.0
SERVER_PORT: 8080

# gRPC Services
GRPC_TLS_ENABLED: true
GRPC_PORT: 5005X  # X = 1-5 for each service

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT: http://lgtm:4317
OTEL_EXPORTER_OTLP_PROTOCOL: grpc
ENV: development
Default credentials are used for development. Always change these for production deployments.

​
View Observability Data

Chronoverse includes built-in observability with Grafana:
  1. Open http://localhost:3000
  2. Navigate to Dashboards
  3. Explore traces, metrics, and logs
The observability stack (LGTM - Loki, Grafana, Tempo, Mimir) is pre-configured and requires no additional setup.

​
Stop Services

When you’re done, stop all services: 
docker compose -f compose.dev.yaml down
To remove all data volumes as well: 
docker compose -f compose.dev.yaml down -v

​
Troubleshooting

Check Docker logs for specific services:
docker compose -f compose.dev.yaml logs [service-name]
Common issues:
  • Port conflicts - ensure ports 3000, 3001, 5432, 6379, 8080, 9440 are available
  • Insufficient resources - allocate at least 4GB RAM to Docker
The init-certs service automatically generates TLS certificates on first run. If you see certificate errors:
# Remove old certificates and restart
rm -rf certs/
docker compose -f compose.dev.yaml up -d
Wait for databases to become healthy:
docker compose -f compose.dev.yaml ps
PostgreSQL and ClickHouse may take 30-60 seconds to initialize on first run.
Check worker logs:
docker compose -f compose.dev.yaml logs scheduling-worker
docker compose -f compose.dev.yaml logs execution-worker
Verify Kafka is running:
docker compose -f compose.dev.yaml ps kafka

​
Next Steps

Installation Guide

Learn about production deployment options

Configuration

Deep dive into configuration options

API Reference

Explore the complete REST API

Architecture

Understand Chronoverse’s internal architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us