Admin Dashboard

The Rakiba admin dashboard provides a web UI and terminal UI for managing local development projects, viewing logs, controlling services, and monitoring your development environment.

Overview

Rakiba includes a powerful admin dashboard for managing your local development environment. It provides both a web UI (port 4000) and a terminal UI (TUI) for developers who prefer the command line.

Both interfaces connect to the same backend and provide equivalent functionality for local development.

Quick Start

# Start the web dashboard
cd rakiba
bb admin

# Open http://localhost:4000

Or use the TUI:

bb admin:tui

Web Dashboard

The web dashboard runs on port 4000 and provides a visual interface for:

Project Management

• View all projects in your projects/ directory
• Start/Stop/Restart projects with one click
• Real-time status showing running state, ports, and resource usage
• Live log streaming with syntax highlighting

Service Monitoring

Monitor the health of managed services:

Log Viewer

Stream logs from any project or service in real-time:

• Filter by level (debug, info, warn, error)
• Search within log output
• Download logs for offline analysis
• Tail mode auto-scrolls to latest entries

Terminal UI (TUI)

The TUI provides the same functionality in a keyboard-driven interface:

bb admin:tui

Navigation

Sections

Project Actions

Managing Projects

Start a Project

From the dashboard, select a project and click Start (or press s in TUI).

This runs the equivalent of:

cd projects/my-app
bb clj

The dashboard manages the process lifecycle, including:

• Starting the nREPL server
• Starting shadow-cljs (if frontend enabled)
• Starting SASS watcher (if SASS files exist)

View Project Status

The project list shows real-time information:

Port Allocation

Projects are automatically assigned ports to avoid conflicts:

Where N is the project index (0 for first project, 1 for second, etc.).

Managing Services

The dashboard can start and stop managed services (Docker Compose):

Available Services

Service Actions

First-Time Setup

If services haven’t been configured yet:

bb services:setup
bb services:up

Then the dashboard will show service status.

Configuration

Dashboard Port

The dashboard always runs on port 4000. This is not configurable to ensure consistency.

GraalVM Native Image

The dashboard is compiled to a native binary for fast startup (~18ms):

# Rebuild if needed
bb admin:build

# Check build status
bb admin:check

JVM Mode

For development on the dashboard itself, use JVM mode:

bb admin:jvm

This provides:

• Hot reload of Clojure code
• nREPL connection
• Slower startup but faster iteration

Styling

The dashboard uses SASS for styling:

# Watch mode (auto-compile on save)
bb admin:sass

# One-time build
bb admin:sass:build

Output is written to resources/admin/public/css/admin.css.

Architecture

The admin dashboard is a full-stack Clojure application:

bb admin
    |
    v
+-------------------+
| GraalVM Native    |  <- Fast startup (~18ms)
| rakiba-admin      |
+-------------------+
    |
    +-- Integrant system
    |   +-- :admin/server (http-kit, port 4000)
    |   +-- :admin/router (Reitit routes)
    |   +-- :admin/broadcaster (WebSocket heartbeat)
    |
    +-- Local project management
    |   +-- Process spawning (clj/cljs/sass)
    |   +-- Port allocation
    |   +-- Log streaming
    |
    +-- Docker service management
        +-- docker-compose up/down
        +-- Health checks

Frontend

• Re-frame for state management
• WebSocket for real-time updates
• SASS for styling

Backend

• http-kit server
• Reitit routing
• Integrant lifecycle management

Troubleshooting

Dashboard Won’t Start

# Check if port 4000 is in use
lsof -i :4000

# Try JVM mode for better error messages
bb admin:jvm

Projects Not Showing

Projects must be in the projects/ directory:

ls projects/
# Should show your project directories

Services Not Responding

# Check Docker is running
docker ps

# Check service status
bb services:status

TUI Display Issues

The TUI requires a terminal with:

• 256 colors support
• UTF-8 encoding
• Minimum 80x24 size

# Check terminal capabilities
echo $TERM
# Should be xterm-256color or similar

Related

• Commands Reference - All bb admin commands
• Managed Services - Service configuration
• VPS Agent - Remote server management