Installation Guide

Get Pushpaka running on your preferred platform

🐧 Linux / macOS

Prerequisites

  • ✓ Go 1.25 or higher
  • ✓ Docker (optional, for containerization)
  • ✓ Git 2.30+

Installation Steps

# Clone the repository
git clone https://github.com/vikukumar/pushpaka.git
cd Pushpaka

# Build the project
go build -o pushpaka ./cmd/pushpaka

# Run in dev mode (SQLite, no external deps)
./pushpaka -dev

# Or run with Docker
docker-compose up -d --build

Access Dashboard

Open your browser and navigate to:

http://localhost:3000

🪟 Windows

Prerequisites

  • ✓ Go 1.25 or higher
  • ✓ Git for Windows
  • ✓ Docker Desktop (optional)
  • ✓ PowerShell 5.1 or higher

Installation Steps

# Open PowerShell as Administrator

# Clone the repository
git clone https://github.com/vikukumar/pushpaka.git
cd Pushpaka

# Build the project
go build -o pushpaka.exe ./cmd/pushpaka

# Run in dev mode
.\pushpaka.exe -dev

Access Dashboard

Open your browser and navigate to:

http://localhost:3000

🐳 Docker / Docker Compose

Quick Start with Docker Compose

# Clone the repository
git clone https://github.com/vikukumar/pushpaka.git
cd Pushpaka

# Start all services using Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f pushpaka

Docker Compose Services

  • Pushpaka API - Port 8080
    Backend API and dashboard
  • Traefik - Port 80, 443
    Reverse proxy and SSL termination
  • PostgreSQL - Port 5432
    Database (optional, can use SQLite)
  • Redis - Port 6379
    Job queue (optional, uses in-process in dev)

Access Services

Dashboard:    http://localhost:3000
API:          http://localhost:8080
Traefik UI:   http://localhost:8081 (if enabled)

🛰️ Remote Worker (Vaahan)

Deploying a Distributed Node

Connect remote hardware or cloud VMs back to your Pushpaka Management API instantly.

Installation

# Build the worker binary
go build -o pushpaka-worker ./cmd/worker

# Launch as a Vaahan (serverless) node
./pushpaka-worker \
  --mode vaahan \
  --server ws://your-api-domain.com \
  --zone-pat YOUR_ZONE_PAT

Configuration Details

  • Zone PAT - Generate this in the Infrastructure > Workers dashboard.
  • Management Server - Your main API address (WSS preferred).
  • Reverse Tunneling - No inbound ports or public IP required on the worker node.

☸️ Kubernetes

Deploy to Kubernetes

Pushpaka can be deployed to Kubernetes using Helm or kubectl manifests.

Prerequisites

  • ✓ kubectl 1.20+
  • ✓ Kubernetes 1.20+ cluster
  • ✓ Helm 3+ (optional, for Helm installation)

Installation

# Create namespace
kubectl create namespace pushpaka

# Deploy using kubectl
kubectl apply -f infrastructure/k8s/ -n pushpaka

# Or deploy using Helm (when available)
helm install pushpaka ./helm/pushpaka -n pushpaka

Note: Kubernetes integration is in development. Check the repository for the latest deployment manifests.

⚙️ Configuration

Environment Variables

DATABASE_URL

Database connection string (PostgreSQL or SQLite)

REDIS_URL

Redis connection string for job queue

PORT

API server port (default: 8080)

DASHBOARD_URL

Frontend dashboard URL

PUSHPAKA_COMPONENT

Component to run: api, worker, all (default: all)

Example .env File

# Database (GORM)
DATABASE_DRIVER=postgres  # postgres, mysql, sqlserver, sqlite
DATABASE_URL=postgresql://user:pass@localhost:5432/pushpaka

# Cache & Queue
REDIS_URL=redis://localhost:6379

# Server
PORT=8080
WORKER_PORT=8081  # Dedicated management stream
DASHBOARD_URL=http://localhost:3000

# Components
PUSHPAKA_COMPONENT=all
ZONE_ID=pushpaka-default-zone

🔧 Troubleshooting

Port Already in Use

If port 8080 (or 3000) is already in use:

# Linux/macOS: Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

# Or specify different port
PORT=9080 ./pushpaka -dev

Build Errors

If you encounter build errors:

# Clear Go cache
go clean -cache
go clean -modcache

# Reinstall dependencies
go mod download
go mod tidy

# Rebuild
go build -o pushpaka ./cmd/main.go

Docker Build Failed

If Docker build fails:

# Clear Docker cache
docker system prune -a

# Rebuild image
docker-compose build --no-cache

# Check logs
docker-compose logs pushpaka

Dashboard Not Loading

Check API connectivity:

# Test API endpoint
curl http://localhost:8080/api/v1/health

# Check logs
docker-compose logs pushpaka

# Ensure API_URL is correct in frontend .env
View Documentation