Deployment

Deploy Rakiba projects to local Docker containers for testing or remote VPS servers for production. Both use the same bb deploy command with zero-downtime blue/green deployment by default.

Overview

Rakiba supports two deployment targets:

Both use the same bb deploy command with the --target flag.

Prerequisites

Local Machine

Where you run bb deploy:

• Babashka (bb) installed
• Docker (for container targets)
• SSH client and rsync (for VPS targets)
• Project built with bb build capability

Target Server (VPS)

Before deploying to a VPS, ensure these are installed:

# Update packages
apt-get update

# Install Java 21, nginx, curl
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-21-jre-headless nginx curl

# Create application user
useradd -m -s /bin/bash rakiba

# Create Java symlink (optional but recommended)
mkdir -p /opt/java
ln -sf /usr/lib/jvm/java-21-openjdk-amd64/* /opt/java/

# Create app directory
mkdir -p /home/rakiba
chown rakiba:rakiba /home/rakiba

Local Sandbox Deployment

Test deployments locally with a production-like environment using Docker containers.

Quick Start

# One-time DNS setup (requires sudo)
bb local:dns-setup

# Create a sandbox
bb local:create ubuntu@24.04 --name dev

# Deploy your project
bb deploy my-app --target dev

# Access it
open http://my-app.rakiba.test:9080

What You Get

A local sandbox provisions a full production stack:

Sandbox Commands

Port Mapping

Multiple sandboxes use incremented ports (9081, 5433, etc.).

VPS Deployment

VPS deployment uses the Rakiba Agent - a lightweight service running on your server that handles deployments, log streaming, and service management. See VPS Agent for the full architecture.

1. Add VPS to Inventory

Register your VPS with Rakiba:

# Basic usage (uses default SSH key and port 22)
bb vps:add root@192.168.1.100 --name prod

# With custom port and key
bb vps:add deploy@192.168.1.100 --name prod --port 2222 --key ~/.ssh/deploy_key

This creates an entry in .remote-inventory.edn.

2. Verify Connectivity

# Quick connectivity check
bb vps:status prod

# Full deployment readiness check (SSH + rsync)
bb vps:verify prod

3. Setup Agent (First Time)

Install the Rakiba agent on your VPS:

bb vps:setup prod

This installs a lightweight agent service that handles deployments and enables remote management from your local Admin Dashboard.

4. Deploy

# Deploy a project
bb deploy myproject --target prod

# Deploy with options
bb deploy myproject --target prod --skip-build --timeout 120

5. Verify Deployment

After deployment, the app is accessible at http://<vps-ip>:8001/ (port 8001 is the default).

curl http://192.168.1.100:8001/api/health

Blue/Green Deployment

By default, Rakiba uses blue/green deployment for zero-downtime updates. This strategy ensures your users never experience downtime during deployments.

How It Works

1. A new version starts on a temporary “blue” port (primary port + 100)
2. Health check verifies the new version is working
3. Nginx switches traffic to the new version
4. Old connections drain gracefully
5. Old service is stopped

Benefits

• Zero downtime during deployment
• Instant rollback if health check fails
• Traffic switch happens in milliseconds

Memory Consideration: Blue/green temporarily runs two JVM processes. Servers with less than 1GB RAM should use the :restart strategy instead.

Configuration

Add a :deployment key to your project’s rakiba.edn:

{:state-management :mount
 :server :jetty
 ;; ... other config ...
 
 :deployment
 {:strategy :blue-green       ; :blue-green (default) or :restart
  :health-check-timeout-ms 120000  ; 2 minutes (default)
  :drain-timeout-ms 30000          ; 30 seconds (default)
  :blue-port-offset 100}}          ; Port offset for blue service (default: 100)

Options

CLI Overrides

CLI flags override rakiba.edn configuration:

# Force legacy restart (overrides :strategy in config)
bb deploy myproject --target prod --no-blue-green

# Custom timeouts (override config values)
bb deploy myproject --target prod --timeout 180 --drain-timeout 60

Precedence: CLI flags > rakiba.edn :deployment > defaults

Deployment Flow

When you run bb deploy, the following steps occur:

1. Resolve Target - Check if target is VPS (.remote-inventory.edn) or container (.local-envs/)
2. Test Connection - Verify SSH connectivity (VPS) or Docker container is running
3. Build - Run bb build to create uberjar (unless --skip-build)
4. Upload - Transfer JAR and .env file via rsync (VPS) or docker cp (container)
5. Install Service - Create systemd unit file
6. Deploy - Blue/green deployment (default) or restart based on strategy
7. Health Check - Poll /api/health until it responds
8. Traffic Switch - Update nginx to route to new version (blue/green only)
9. Drain & Cleanup - Gracefully stop old service (blue/green only)

Command Reference

VPS Management

Deployment

Deployment Options

Container Management

Troubleshooting

SSH Connection Failed

# Check SSH connectivity manually
ssh -i /path/to/key -p <port> user@host "echo ok"

# Verify key permissions
chmod 600 ~/.ssh/id_rsa

Service Won’t Start

# Check service status on target
ssh user@host "systemctl status rakiba-<project>.service"

# View logs
ssh user@host "journalctl -u rakiba-<project>.service -n 50"

Health Check Timeout

The health check polls /api/health for 60 seconds by default. If your app takes longer to start:

bb deploy myproject --target prod --timeout 120

Permission Denied on Upload

For non-root SSH users, ensure:

1. The SSH user owns /home/rakiba/ or has write access
2. The SSH user has passwordless sudo for systemctl commands

# Fix ownership (run as root)
chown -R deploy:deploy /home/rakiba

# Add sudo access for systemctl
echo "deploy ALL=(ALL) NOPASSWD: /bin/systemctl" >> /etc/sudoers.d/deploy

Files Reference