Skip to main content

Setup

This guide will help you set up Pulse on your local machine or server. After setup, you can integrate Pulse SDKs into your applications.

📚 SDK Documentation: Once Pulse is running, see the Android SDK and React Native SDK guides for integrating Pulse into your mobile applications.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Docker: 20.10+ and Docker Compose 2.0+
  • Java: 17+ (for backend development)
  • Node.js: 18+ (for frontend development)
  • Android Studio: Latest version (for Android SDK development)
  • Memory: 8GB RAM (4GB available for Docker)
  • Disk: 20GB free space

Quick Start (5 Minutes)​

Get Pulse up and running in just 5 minutes with Docker Compose.

1. Clone the Repository​

git clone https://github.com/dream-horizon-org/pulse.git
cd pulse

2. Setup Environment​

cd deploy
cp .env.example .env
# Edit .env with your configuration (defaults work for local development)

The .env.example file contains all necessary environment variables with sensible defaults for local development. You can customize them as needed.

3. Start All Services​

# Make scripts executable
chmod +x scripts/*.sh

# Build and start
./scripts/quickstart.sh

This will:

  1. Build Docker images for all services
  2. Start all containers
  3. Automatically create database tables (on first run only)
  4. Set up networking between services

4. Access the Platform​

Once all services are running, you can access:

ServiceURLDescription
Frontend (UI)http://localhost:3000Pulse web interface
Backend APIhttp://localhost:8080REST API endpoint
Health Checkhttp://localhost:8080/healthBackend health status
MySQLhttp://localhost:3307Metadata database
ClickHouse HTTPhttp://localhost:8123ClickHouse HTTP interface
ClickHouse Nativehttp://localhost:9000ClickHouse native protocol
OTEL Collector (gRPC)http://localhost:4317OTLP gRPC endpoint
OTEL Collector (HTTP)http://localhost:4318OTLP HTTP endpoint

5. Verify Installation​

# Check all services are running
docker-compose ps

# Check backend health
curl http://localhost:8080/healthcheck

# View logs
./scripts/logs.sh

You should see all services in "Up" status. The health check should return a successful response.

Development Setup​

For development, you can run services individually without Docker.

Frontend Development​

cd pulse-ui
yarn install
yarn start           # Start dev server (http://localhost:3000)

The frontend will hot-reload on code changes. Make sure the backend API is running and accessible.

Backend Development​

cd backend/server
rm -rf src/main/generated
mvn clean install   # Build project
mvn package        # Create JAR

export MYSQL_WRITER_HOST=mysql
export MYSQL_READER_HOST=mysql
export MYSQL_DATABASE=pulse_db
export MYSQL_USER=pulse_user
export MYSQL_PASSWORD=pulse_password
export MYSQL_WRITER_MAX_POOL_SIZE=10
export MYSQL_READER_MAX_POOL_SIZE=10

export CONFIG_SERVICE_APPLICATION_CRONMANAGERBASEURL="http://pulse-alerts-cron-uat.dream11.local/cron"
export CONFIG_SERVICE_APPLICATION_SERVICEURL="http://pulse-server-uat.dream11.local"
export CONFIG_SERVICE_APPLICATION_GOOGLEOAUTHCLIENTID="abcdbabcd.apps.googleusercontent.com"
export CONFIG_SERVICE_APPLICATION_GOOGLEOAUTHENABLED=false
export CONFIG_SERVICE_APPLICATION_JWTSECRET="dev-secret-key-at-least-32-characters-long-for-local-testing-only"

export CLICKHOUSE_R2DBC_URL="r2dbc:clickhouse:http://clickhouse:8123/otel"
export CLICKHOUSE_USERNAME=pulse_user
export CLICKHOUSE_PASSWORD=pulse_password
export CLICKHOUSE_HOST=clickhouse
export CLICKHOUSE_PORT=8123

java -jar target/pulse-server/pulse-server.jar

Ensure MySQL and ClickHouse are running (via Docker or local installation).

Android SDK Development​

cd pulse-android-otel
./gradlew assemble  # Build SDK
./gradlew check     # Run tests and checks
./gradlew spotlessApply  # Format code

📚 Android SDK Documentation →

React Native SDK Development​

cd pulse-react-native-otel
npm install
npm run build      # Build TypeScript
cd example
yarn
yarn android    # Run example app (Android)

📚 React Native SDK Documentation →

Docker Deployment​

Using Docker Compose​

The easiest way to run Pulse is using Docker Compose:

cd deploy
docker-compose up --build

This will:

  1. Build Docker images for all services
  2. Start all containers
  3. Automatically create database tables (on first run only)
  4. Set up networking between services

Build Individual Services​

# Build only the UI
docker-compose build pulse-ui

# Build only the server
docker-compose build pulse-server

# Build all services
docker-compose build

Start/Stop Services​

# Start all services in detached mode
docker-compose up -d

# Start specific service
docker-compose up -d pulse-ui

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

View Logs​

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f pulse-server
docker-compose logs -f pulse-ui

# View last 100 lines
docker-compose logs --tail=100 pulse-server

Configuration​

Environment Variables​

Key environment variables to configure:

MySQL Configuration

CONFIG_SERVICE_APPLICATION_MYSQL_HOST=localhost
CONFIG_SERVICE_APPLICATION_MYSQL_PORT=3306
CONFIG_SERVICE_APPLICATION_MYSQL_DATABASE=pulse_db
CONFIG_SERVICE_APPLICATION_MYSQL_USER=pulse_user
CONFIG_SERVICE_APPLICATION_MYSQL_PASSWORD=pulse_password

ClickHouse Configuration

CONFIG_SERVICE_APPLICATION_CLICKHOUSE_HOST=localhost
CONFIG_SERVICE_APPLICATION_CLICKHOUSE_PORT=8123
CONFIG_SERVICE_APPLICATION_CLICKHOUSE_DATABASE=otel
CONFIG_SERVICE_APPLICATION_CLICKHOUSE_USER=default
CONFIG_SERVICE_APPLICATION_CLICKHOUSE_PASSWORD=

Server Configuration

CONFIG_SERVICE_APPLICATION_SERVER_PORT=8080
CONFIG_SERVICE_APPLICATION_SERVER_HOST=0.0.0.0

Authentication Configuration

VAULT_SERVICE_GOOGLE_CLIENT_ID=your-google-client-id
VAULT_SERVICE_JWT_SECRET=your-jwt-secret

Frontend Configuration

REACT_APP_GOOGLE_CLIENT_ID=your-google-client-id
REACT_APP_OTEL_ENDPOINT=http://localhost:4318
REACT_APP_OTEL_SERVICE_NAME=pulse-ui
REACT_APP_OTEL_SERVICE_VERSION=1.0.0

Database Setup​

MySQL​

MySQL is used for storing metadata (users, alerts, configurations).

The database tables are automatically created on first startup when using Docker Compose. If you need to manually initialize:

docker-compose exec mysql mysql -u pulse_user -ppulse_password pulse_db < deploy/db/mysql-init.sql

ClickHouse​

ClickHouse is used for time-series analytics data.

The schema is automatically created on first startup. For manual setup:

docker-compose exec clickhouse clickhouse-client < backend/ingestion/clickhouse-otel-schema.sql

Testing​

Run All Tests​

# Frontend tests
cd pulse-ui && npm test

# Backend tests
cd backend/server && mvn test

# Android SDK tests
cd pulse-android-otel && ./gradlew check

# React Native SDK tests
cd pulse-react-native-otel && npm test

Integration Tests​

cd deploy
docker-compose up -d
# Run integration test suite
./scripts/test-integration.sh

Troubleshooting​

Port Already in Use​

If ports 3000 or 8080 are already in use:

# Find process using port
lsof -i :3000  # or :8080
kill -9 <PID>

Or modify docker-compose.yml to use different ports.

Database Connection Failed​

# Restart databases
docker-compose restart mysql clickhouse

# Check logs
docker-compose logs mysql clickhouse

# Verify database is accessible
docker-compose exec mysql mysql -u pulse_user -ppulse_password -e "SELECT 1"
docker-compose exec clickhouse clickhouse-client --query "SELECT 1"

Build Failures​

# Clean rebuild
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

Container Keeps Restarting​

Check logs for errors:

docker-compose logs pulse-server
docker-compose logs pulse-ui
docker-compose logs otel-collector

Common causes:

  • Database connection issues
  • Missing environment variables
  • Port conflicts
  • Insufficient memory

Database Tables Not Created​

If tables are missing after first startup:

# Use the reset script
./scripts/reset-databases.sh

# Or manual reset
docker-compose down
docker volume rm deploy_mysql-data deploy_clickhouse-data
docker-compose up -d

SDK Integration Issues​

If you're having issues integrating the SDKs:

Monitoring & Observability​

Health Checks​

# Backend health
curl http://localhost:8080/health

# Database connectivity
docker-compose exec pulse-server curl http://localhost:8080/health

# OTEL Collector health
curl http://localhost:13133/

View Logs​

# View all logs
docker-compose logs -f

# View specific service
docker-compose logs -f pulse-server
docker-compose logs -f pulse-ui
docker-compose logs -f otel-collector

# View with timestamp
docker-compose logs -f -t pulse-server

Container Stats​

# Container resource usage
docker stats

# OTEL Collector metrics
curl http://localhost:8888/metrics

Next Steps​

Now that Pulse is set up, you can:

  1. Integrate Android SDK - Add Pulse to your Android app
  2. Integrate React Native SDK - Add Pulse to your React Native app
  3. Explore Instrumentation - Learn about automatic instrumentation
  4. API Documentation - Explore the API reference