Darpan - Linux Developer Service Monitor

Darpan (दर्पण) means "mirror" in Sanskrit - a real-time reflection of your entire development environment.

Stop checking services one by one. Darpan shows you everything at a glance.

📋 Table of Contents

• What is Darpan?
• Why Use Darpan?
• Installation
• Quick Start Tutorial
• Detailed Usage Guide
• Configuration
• Real-World Examples
• Troubleshooting
• Advanced Features

---

🎯 What is Darpan?

Darpan is a developer-friendly service monitoring tool for Linux that automatically detects and monitors all your development services in one place.

The Problem It Solves

As a developer, you probably run multiple services:

# You do this all day:
docker ps                          # Check Docker
systemctl status postgresql        # Check PostgreSQL
redis-cli ping                     # Check Redis
curl localhost:3000               # Check your app
lsof -i :8080                     # Find what's on port 8080

This is tedious and time-consuming!

The Solution

With Darpan:

darpan watch    # See everything at once!

One command shows you:

• ✅ All running services
• ✅ Their health status
• ✅ Response times
• ✅ Why services are down
• ✅ Live activity logs

---

💡 Why Use Darpan?

For Solo Developers

• 🚀 Start your day faster: Know what's running before you begin coding
• 🔍 Debug quicker: Instantly see which service is down
• 🧘 Reduce cognitive load: One tool instead of 10 commands

For Teams

• 📊 Shared understanding: Everyone sees the same service status
• 🎯 Faster onboarding: New devs understand the stack immediately
• 🔧 Better debugging: "Is Redis down for you too?"

Key Features

• 🔎 Auto-detection: Finds services automatically (ports, processes, Docker)
• ❤️ Health checks: Port, HTTP, database-specific checks
• 🖥️ Two interfaces: CLI for quick checks, TUI for monitoring
• ⚙️ Zero config: Works immediately, configure only when needed
• 🐳 Docker aware: Detects and monitors containers
• 📱 Lightweight: <20MB RAM, <5.5MB binary

---

📦 Installation

Prerequisites

• Operating System: Linux (Ubuntu, Debian, Arch, etc.)
• Rust: 1.70 or later (for building from source)
• Optional: Docker (for Docker container detection)

Method 1: Build from Source (Recommended)

Step 1: Clone the Repository

cd ~
git clone https://github.com/codeBunny2022/darpan.git
cd darpan

Step 2: Build and Install

# Build the release version (optimized)
cargo build --release

# Install globally (requires sudo)
sudo cp target/release/darpan /usr/local/bin/

# Or install for current user only
cargo install --path .

Step 3: Verify Installation

darpan --version
# Output: darpan 0.1.0

✅ Done! Darpan is now available system-wide.

Method 2: Install via Cargo (Future)

# Coming soon!
cargo install darpan

---

🚀 Quick Start Tutorial

Let's learn Darpan with a hands-on tutorial!

Tutorial 1: Your First Status Check

Step 1: Check What's Running

Open a terminal and run:

darpan status

What you'll see:

Project: your-current-directory

╭───────────┬────────────┬──────────┬────────────────┬──────────╮
│ STATUS    │ NAME       │ TYPE     │ HOST:PORT      │ RESPONSE │
├───────────┼────────────┼──────────┼────────────────┼──────────┤
│ ✓ Healthy │ PostgreSQL │ Database │ localhost:5432 │ 12ms     │
│ ✓ Healthy │ Redis      │ Cache    │ localhost:6379 │ 3ms      │
╰───────────┴────────────┴──────────┴────────────────┴──────────╯

All 2 services are healthy ✓

Understanding the output:

• ✓ Green checkmark: Service is healthy
• ⚠ Yellow warning: Service is degraded
• ✗ Red X: Service is down
• Response time: How long the health check took

Step 2: Understand What Was Detected

Darpan automatically found:

• PostgreSQL on port 5432 (standard PostgreSQL port)
• Redis on port 6379 (standard Redis port)

How? Darpan:

1. Scanned localhost ports 3000-9999
2. Found open ports 5432 and 6379
3. Identified them as PostgreSQL and Redis
4. Checked their health

Tutorial 2: Interactive Monitoring

Step 1: Launch the TUI (Terminal User Interface)

darpan watch

What you'll see:

╔═══════════════════════════════════════════════╗
║  Darpan - your-directory | Live Monitor      ║
╠═══════════════════════════════════════════════╣
║ >> ✓ PostgreSQL    Database    :5432    12ms ║
║    ✓ Redis          Cache       :6379     3ms ║
╠═══════════════════════════════════════════════╣
║ Quick Info:                                   ║
║   Service: PostgreSQL                         ║
║   Status: ✓ HEALTHY                           ║
╠═══════════════════════════════════════════════╣
║ Live Logs:                                    ║
║   [18:13:33] Detected 2 services              ║
║   [18:13:38] Health check: 2/2 healthy        ║
╠═══════════════════════════════════════════════╣
║ q: quit | Enter: details | ↑↓: navigate      ║
╚═══════════════════════════════════════════════╝

Step 2: Navigate and Explore

Try these controls:

1. Move up/down: Press ↑ and ↓ (or j and k)
   • Watch the >> selector move
   • Quick Info panel updates automatically
2. View details: Press Enter on any service
   • See full service information
   • View process ID, command line
   • See error messages and suggestions
3. Go back: Press q or Esc
   • Returns to main dashboard
4. Refresh: Press r
   • Forces an immediate health check
   • Watch the logs update
5. Quit: Press q from the main dashboard

Step 3: Watch Live Updates

Leave the TUI running for a minute:

• Auto-refreshes every 5 seconds
• Live logs show activity
• Status updates automatically
• Time since last update shown at bottom

Try this experiment:

1. Keep darpan watch running
2. In another terminal, stop a service: sudo systemctl stop redis
3. Watch Darpan detect it within 5 seconds!
4. Restart Redis: sudo systemctl start redis
5. Watch it turn green again!

Tutorial 3: Troubleshooting a Down Service

Step 1: Simulate a Problem

Stop Redis temporarily:

sudo systemctl stop redis-server

Step 2: Check Status

darpan status

Output:

╭────────────┬────────────┬──────────┬────────────────┬──────────╮
│ STATUS     │ NAME       │ TYPE     │ HOST:PORT      │ RESPONSE │
├────────────┼────────────┼──────────┼────────────────┼──────────┤
│ ✓ Healthy  │ PostgreSQL │ Database │ localhost:5432 │ 12ms     │
│ ✗ Down     │ Redis      │ Cache    │ localhost:6379 │ N/A      │
╰────────────┴────────────┴──────────┴────────────────┴──────────╯

1/2 services healthy. 1 need attention!

Step 3: Investigate the Problem

Use the why command:

darpan why "Redis"

Output:

Service: Redis
────────────────────────────────────────────────────────
Status: DOWN ✗
Reason: Port not reachable: Connection refused
Location: localhost:6379
Process ID: Not running

Suggestion: Check if Redis is running and accepting connections

Last checked: 2026-01-20 18:30:45

This tells you:

• ❌ Redis is not running
• 📍 Expected on port 6379
• 💡 Suggestion: Check if it's running

Step 4: Fix the Problem

sudo systemctl start redis-server

Step 5: Verify the Fix

darpan status

✅ All services are healthy!

---

📚 Detailed Usage Guide

Command Reference

darpan status

Shows current status of all services.

Basic usage:

darpan status

Options:

# JSON output (for scripts)
darpan status --format json

# Specific project
darpan status --path ~/my-project

# With debug logging
darpan --verbose status

When to use:

• 🌅 Starting your workday
• 🐛 Before debugging
• 🚀 Before deploying
• 🔄 After restarting services

darpan watch

Interactive TUI with live monitoring.

Basic usage:

darpan watch

Controls:

Key	Action
↑ / k	Move selection up
↓ / j	Move selection down
Enter	View service details
q	Quit (or back from details)
Esc	Back to dashboard
r	Manual refresh

When to use:

• 👀 Continuous monitoring
• 🔍 Troubleshooting complex issues
• 📊 During development
• 🎯 When waiting for services to start

darpan why <service-name>

Detailed troubleshooting for a specific service.

Basic usage:

darpan why "PostgreSQL"
darpan why "Redis"
darpan why "Backend API"

Example output:

Service: Backend API
────────────────────────────────────────────────────────
Status: DOWN ✗
Reason: Process not running
Location: localhost:3001
Process ID: Not found
Expected: node dist/server.js

Suggestion: Run 'npm run dev' in project directory

Last checked: 2026-01-20 18:35:22

When to use:

• ❓ Service shows as down
• 🐛 Debugging startup issues
• 📖 Learning about service configuration

darpan init

Creates a .darpan.yml configuration file.

Basic usage:

cd ~/my-project
darpan init

Creates:

version: 1

services:
  - name: Backend API
    type: http_server
    port: 3001
    health_check:
      type: http
      path: /api/health
    tags: [critical, backend]
    
  - name: PostgreSQL
    type:
      database: postgres
    port: 5432
    health_check:
      type: postgres
      database: myapp_dev

When to use:

• 📝 Custom service names
• 🎯 Specific health checks
• 👥 Sharing config with team
• 🏷️ Organizing with tags

Working with Different Projects

Scenario 1: Multiple Projects

You can use Darpan in any project without any setup:

Project A: E-commerce App

cd ~/projects/ecommerce
darpan watch
# Detects: PostgreSQL, Redis, Node.js backend, React frontend

Project B: Analytics Service

cd ~/projects/analytics
darpan watch
# Detects: MySQL, Python API, Celery workers

Project C: Microservices

cd ~/projects/microservices
darpan watch
# Detects: Multiple Docker containers, APIs

Scenario 2: Service-Specific Configs

Each project can have its own .darpan.yml:

Backend API Project:

cd ~/api-service
cat > .darpan.yml << 'EOF'
version: 1
services:
  - name: FastAPI Backend
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /health
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
EOF

darpan watch

Frontend Project:

cd ~/frontend
cat > .darpan.yml << 'EOF'
version: 1
services:
  - name: React Dev Server
    type: http_server
    port: 3000
  - name: API Backend
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /api/health
EOF

darpan watch

---

⚙️ Configuration

Configuration Hierarchy

Darpan uses a three-level configuration system:

1. System Defaults (built-in)
   ↓
2. User Config (~/.config/darpan/config.yml)
   ↓
3. Project Config (.darpan.yml)

User Configuration

Create ~/.config/darpan/config.yml for global settings:

mkdir -p ~/.config/darpan
cat > ~/.config/darpan/config.yml << 'EOF'
global:
  theme: dark
  refresh_interval: 5  # seconds

detection:
  enabled_detectors: [config, port, process, docker]
  port_range: [3000, 9999]  # Ports to scan

health_checks:
  timeout: 3  # seconds
  retry_count: 2

projects:
  - path: ~/work/client-a
    auto_load: true
  - path: ~/work/client-b
    auto_load: true
EOF

Project Configuration

Create .darpan.yml in your project root:

cd ~/my-project
cat > .darpan.yml << 'EOF'
version: 1

services:
  # Web Server
  - name: Backend API
    type: http_server
    port: 3001
    health_check:
      type: http
      path: /api/health
      expected_status: 200
    tags: [critical, backend]
    
  # Database
  - name: PostgreSQL
    type:
      database: postgres
    port: 5432
    health_check:
      type: postgres
      database: myapp_dev
    tags: [database, critical]
    
  # Cache
  - name: Redis
    type:
      cache: redis
    port: 6379
    health_check:
      type: redis
    tags: [cache]
    
  # Custom service
  - name: Celery Worker
    type: custom
    process: python celery_worker.py
    health_check:
      type: custom
      script: ./check_celery.sh
    tags: [worker]

# Service dependencies
dependencies:
  - service: Backend API
    depends_on: [PostgreSQL, Redis]
EOF

Supported Service Types

# HTTP Server
type: http_server

# Database
type: { database: postgres }  # postgres, mysql, mongodb, sqlite

# Cache
type: { cache: redis }  # redis, memcached

# Message Queue
type: { message_queue: rabbitmq }  # rabbitmq, kafka, redis

# Search Engine
type: { search: elasticsearch }  # elasticsearch, meilisearch

# Docker Container
type: docker_container

# Custom
type: custom

Health Check Types

# Port connectivity (default)
health_check:
  type: port

# HTTP endpoint
health_check:
  type: http
  path: /health
  expected_status: 200

# PostgreSQL
health_check:
  type: postgres
  database: mydb

# Redis
health_check:
  type: redis

# MySQL
health_check:
  type: mysql
  database: mydb

# Custom script
health_check:
  type: custom
  script: ./health_check.sh
  timeout: 5s

---

🌟 Real-World Examples

Example 1: Full-Stack MERN App

Setup:

cd ~/mern-app
darpan init

Edit .darpan.yml:

version: 1

services:
  - name: MongoDB
    type: { database: mongodb }
    port: 27017
    tags: [database]
    
  - name: Express Backend
    type: http_server
    port: 5000
    health_check:
      type: http
      path: /api/health
    tags: [backend, critical]
    
  - name: React Frontend
    type: http_server
    port: 3000
    tags: [frontend]
    
  - name: Redis Session Store
    type: { cache: redis }
    port: 6379
    tags: [cache]

dependencies:
  - service: Express Backend
    depends_on: [MongoDB, Redis Session Store]
  - service: React Frontend
    depends_on: [Express Backend]

Usage:

# Start your services
mongod &
redis-server &
cd backend && npm run dev &
cd frontend && npm start &

# Monitor everything
darpan watch

Example 2: Django + PostgreSQL

cd ~/django-project
cat > .darpan.yml << 'EOF'
version: 1

services:
  - name: Django Dev Server
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /admin/
    tags: [web]
    
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
    health_check:
      type: postgres
      database: django_db
    tags: [database]
    
  - name: Celery Worker
    type: custom
    process: celery -A myapp worker
    tags: [worker]
    
  - name: Celery Beat
    type: custom
    process: celery -A myapp beat
    tags: [scheduler]

dependencies:
  - service: Django Dev Server
    depends_on: [PostgreSQL]
  - service: Celery Worker
    depends_on: [PostgreSQL, Redis]
EOF

Example 3: Microservices with Docker

cd ~/microservices
cat > .darpan.yml << 'EOF'
version: 1

services:
  - name: Auth Service
    type: http_server
    port: 8001
    health_check:
      type: http
      path: /health
    tags: [microservice, critical]
    
  - name: User Service
    type: http_server
    port: 8002
    health_check:
      type: http
      path: /health
    tags: [microservice]
    
  - name: Payment Service
    type: http_server
    port: 8003
    health_check:
      type: http
      path: /health
    tags: [microservice, critical]
    
  - name: Notification Service
    type: http_server
    port: 8004
    health_check:
      type: http
      path: /health
    tags: [microservice]
    
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
    tags: [database]
    
  - name: Redis
    type: { cache: redis }
    port: 6379
    tags: [cache]
    
  - name: RabbitMQ
    type: { message_queue: rabbitmq }
    port: 5672
    tags: [queue]
EOF

With Docker Compose:

docker-compose up -d
darpan watch
# Automatically detects all containers!

---

🔧 Troubleshooting

Common Issues and Solutions

Issue 1: No Services Detected

Symptom:

darpan status
# No services detected.

Solutions:

1. Check if services are actually running:

# Check open ports
ss -tlnp | grep LISTEN

# Check processes
ps aux | grep postgres
ps aux | grep redis

2. Verify port range: Create ~/.config/darpan/config.yml:

detection:
  port_range: [1000, 65535]  # Scan wider range

3. Use explicit configuration:

darpan init
# Edit .darpan.yml to define your services

Issue 2: Service Shows as Down but It's Running

Symptom:

✗ Down     │ Redis      │ Cache    │ localhost:6379 │ N/A

Solutions:

1. Check the actual service:

redis-cli ping
# Should return: PONG

2. Check if port is accessible:

telnet localhost 6379
# or
nc -zv localhost 6379

3. Configure custom health check:

services:
  - name: Redis
    type: { cache: redis }
    port: 6379
    health_check:
      type: redis  # Use Redis-specific check
      timeout: 5s
      retry_count: 3

Issue 3: Docker Containers Not Detected

Symptom: Docker containers running but not showing in Darpan.

Solutions:

1. Check Docker access:

docker ps
# If this fails, Docker daemon might not be running

2. Add user to docker group:

sudo usermod -aG docker $USER
# Logout and login again

3. Enable Docker detector:

# ~/.config/darpan/config.yml
detection:
  enabled_detectors: [config, port, process, docker]

Issue 4: Permission Denied Errors

Symptom:

Error: Permission denied (os error 13)

Solutions:

1. Darpan doesn't need sudo for basic functionality
2. For Docker: Add user to docker group (see above)
3. For system services: Run status checks work without sudo

Issue 5: TUI Shows Garbled Text

Symptom: Terminal display is corrupted.

Solutions:

1. Reset terminal:

reset

2. Use modern terminal:

• ✅ GNOME Terminal
• ✅ Konsole
• ✅ Alacritty
• ✅ iTerm2 (if on Mac via WSL)

3. Check terminal size:

# TUI needs at least 80x24
echo $COLUMNS x $LINES

---

🚀 Advanced Features

JSON Output for Automation

Export service status as JSON:

# Get all services
darpan status --format json

# Parse with jq
darpan status --format json | jq '.[] | select(.port == 5432)'

# Count healthy services
darpan status --format json | jq '[.[] | select(.health_status.status == "Healthy")] | length'

# Get unhealthy services
darpan status --format json | jq '[.[] | select(.health_status.status != "Healthy")] | .[].name'

Integration with Scripts

Health check script:

#!/bin/bash
# check_services.sh

OUTPUT=$(darpan status --format json)
UNHEALTHY=$(echo $OUTPUT | jq '[.[] | select(.health_status.status != "Healthy")] | length')

if [ $UNHEALTHY -gt 0 ]; then
    echo "❌ $UNHEALTHY service(s) are unhealthy!"
    echo $OUTPUT | jq '[.[] | select(.health_status.status != "Healthy")] | .[].name'
    exit 1
else
    echo "✅ All services are healthy"
    exit 0
fi

Pre-deployment check:

#!/bin/bash
# pre_deploy.sh

echo "Checking services before deployment..."
darpan status

if darpan status --format json | jq -e '[.[] | select(.health_status.status != "Healthy")] | length == 0' > /dev/null; then
    echo "✅ All services healthy. Proceeding with deployment."
    ./deploy.sh
else
    echo "❌ Some services are unhealthy. Aborting deployment."
    darpan status
    exit 1
fi

Custom Health Check Scripts

Example: Custom health check for Celery:

# check_celery.sh
#!/bin/bash
celery -A myapp inspect active >/dev/null 2>&1
if [ $? -eq 0 ]; then
    exit 0  # Healthy
else
    exit 1  # Unhealthy
fi

Configuration:

services:
  - name: Celery Worker
    type: custom
    process: celery worker
    health_check:
      type: custom
      script: ./check_celery.sh
      timeout: 5s

Tags for Organization

Use tags to organize and filter services:

services:
  - name: Auth API
    tags: [critical, microservice, auth]
  - name: Payment Service
    tags: [critical, microservice, payment]
  - name: Analytics Worker
    tags: [worker, non-critical]
  - name: Cache Layer
    tags: [infrastructure, cache]

---

📖 Best Practices

1. Start Simple

• Begin without .darpan.yml
• Let auto-detection work
• Add config only when needed

2. Use Meaningful Names

# ❌ Bad
- name: Service 1
- name: Server

# ✅ Good
- name: User Authentication API
- name: Payment Processing Service

3. Tag Appropriately

tags: [critical, backend]  # For core services
tags: [optional, worker]   # For non-critical services

4. Document Health Checks

- name: API Gateway
  health_check:
    type: http
    path: /health  # Document why this endpoint

5. Share Configs with Team

# Commit .darpan.yml to git
git add .darpan.yml
git commit -m "Add Darpan service monitoring config"

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Links

• 🐛 Report a Bug
• 💡 Request a Feature
• 📖 Documentation

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• Built with Rust
• TUI powered by Ratatui
• Inspired by tools like htop, docker-compose, and systemctl

---

📚 Additional Resources

• QUICKSTART.md - 5-minute quick start guide
• TUI_IMPROVEMENTS.md - TUI features and updates
• CHANGELOG.md - Version history
• FIXED_ISSUES.md - Recent bug fixes

---

💬 Support

Need help?

• 📖 Read the QUICKSTART.md
• 🔍 Check FIXED_ISSUES.md
• 🐛 Open an issue

---

Made with ❤️ for developers who are tired of checking services manually

# Try it now!
darpan watch