doku-cli

Doku CLI

Local development environment manager with Docker, Traefik, and SSL

Doku is a CLI tool that simplifies running and managing Docker-based services locally with automatic service discovery, DNS routing, and SSL certificates.

Features

• 🚀 One-command setup - Get services running in seconds
• 🔒 HTTPS by default - Local SSL certificates that just work
• 🌐 Clean URLs - Access services via service.doku.local instead of localhost:port
• 🔗 Service discovery - Automatic connection string generation
• 📦 Version management - Run multiple versions of the same service
• 🎯 Local development focus - Optimized for developer productivity
• 💪 Resource control - Set CPU and memory limits per service
• 🏗️ API Gateway pattern - Internal-only services for microservices architecture
• 🔐 Environment management - Secure environment variable handling with masking
• 📋 Service catalog - Curated collection of 25+ popular development services
• 🔄 Full lifecycle management - Start, stop, restart, and remove services with ease
• 🧩 Multi-container services - Deploy complex services with multiple containers
• 🔗 Dependency management - Automatic installation of service dependencies
• 🔌 Port mapping - Map container ports to host for direct access via localhost
• 🐳 Custom projects - Build and run from your own Dockerfiles with --path flag
• ⚡ Dynamic configuration - Update environment variables without rebuilding containers

Quick Start

Installation

# Using curl
curl -fsSL https://raw.githubusercontent.com/dokulabs/doku-cli/main/scripts/install.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/dokulabs/doku-cli/main/scripts/install.sh | bash

Verify installation:

doku version

First-Time Setup

# Initialize Doku on your system
doku init

This will:

• Check Docker availability
• Install SSL certificates (mkcert)
• Configure DNS for *.doku.local
• Set up Traefik reverse proxy
• Download service catalog

Install Your First Service

# Install PostgreSQL
doku install postgres

# Install with specific version
doku install postgres:14 --name postgres-14

# Install with custom environment variables
doku install postgres \
  --env POSTGRES_PASSWORD=mysecret \
  --env POSTGRES_DB=myapp

# Install with resource limits
doku install redis --memory 512m --cpu 1.0

# Install with port mapping for direct access
doku install postgres --port 5432

# Install with multiple port mappings (e.g., RabbitMQ)
doku install rabbitmq --port 5672 --port 15672

# Install as internal service (no external access)
doku install redis --internal

Install Custom Projects

Run your own applications from Dockerfiles:

# Install a custom frontend application
doku install frontend --path=./my-frontend-app

# Install backend as internal service
doku install api --path=./backend --internal --port 4000

# Install with environment variables
doku install myapp --path=./myapp \
  --env DATABASE_URL=postgresql://postgres@postgres:5432/mydb \
  --env API_KEY=secret123 \
  --port 8080

📖 See the complete guide: Custom Projects Guide

Manage Environment Variables

Update configuration dynamically without rebuilding:

# View environment variables
doku env frontend

# View with actual values (unmask sensitive data)
doku env frontend --show-values

# Export format for shell sourcing
doku env frontend --export > frontend.env

# Set new variables
doku env set frontend API_KEY=newsecret DEBUG=true

# Auto-restart after changes
doku env set frontend API_KEY=newsecret --restart

# Remove variables
doku env unset frontend OLD_KEY

# Interactive editing (add, edit, delete variables)
doku env edit frontend

Manage Services

# List running services
doku list

# List all services (including stopped)
doku list --all

# Start a service
doku start postgres

# Stop a service
doku stop postgres

# Restart a service
doku restart postgres

# View logs
doku logs postgres -f

# Get detailed service info
doku info postgres

# View environment variables
doku env postgres

# Remove a service
doku remove postgres

Upgrade Doku CLI

Keep your doku CLI up to date with the latest features and fixes:

# Check current version
doku version

# Upgrade to the latest version
doku self upgrade

# Upgrade without confirmation prompt
doku self upgrade --force

The upgrade command will:

• Check for the latest version on GitHub
• Download the appropriate binary for your platform
• Replace the current binary with the new version
• Verify the installation

Architecture

┌─────────────────────────────────────────┐
│           User (Browser/CLI)            │
│    https://service.doku.local          │
└────────────────┬────────────────────────┘
                 │
                 ▼
      ┌──────────────────────┐
      │   Traefik Proxy      │
      │   (Port 80/443)      │
      └──────────┬───────────┘
                 │
   ┌─────────────┴─────────────┐
   │  doku-network (bridge)    │
   │                            │
   │  ┌────────┐  ┌────────┐  │
   │  │postgres│  │ redis  │  │
   │  └────────┘  └────────┘  │
   └────────────────────────────┘

Available Services

📋 Browse the complete service catalog with install commands: Doku Service Catalog

The catalog includes 25 services: PostgreSQL, MySQL, MongoDB, MariaDB, ClickHouse, Redis, Memcached, RabbitMQ, Kafka, Elasticsearch, Grafana, Prometheus, Jaeger, SigNoz, Sentry, Dozzle, Nginx, MailHog, Adminer, phpMyAdmin, LocalStack, MinIO, Vault, Keycloak, and Zookeeper.

# Browse services locally
doku catalog
doku catalog --category database
doku catalog search postgres
doku catalog show postgres

Configuration

Doku stores configuration in ~/.doku/:

~/.doku/
├── config.toml          # Main configuration
├── catalog/             # Service catalog
├── traefik/             # Traefik config
├── certs/               # SSL certificates
└── services/            # Service definitions

Custom Domain

By default, Doku uses doku.local. You can customize:

doku init --domain mydev.local

Commands Reference

Common Flags

• --help, -h - Show help for any command
• --verbose, -v - Verbose output
• --quiet, -q - Quiet mode (minimal output)
• --yes, -y - Skip confirmation prompts (for remove/uninstall)
• --force, -f - Force operation

Install Flags

• --path - Path to project directory with Dockerfile (for custom projects)
• --name, -n - Custom instance name
• --env, -e - Environment variables (KEY=VALUE)
• --memory - Memory limit (e.g., 512m, 1g)
• --cpu - CPU limit (e.g., 0.5, 1.0)
• --port, -p - Port mappings (can be specified multiple times)
  • Format: --port 5432 (maps container port to same host port)
  • Format: --port 5433:5432 (maps container port 5432 to host port 5433)
• --volume - Volume mounts (host:container)
• --internal - Install as internal service (no external access)
• --skip-deps - Skip dependency installation
• --no-auto-install-deps - Prompt before installing dependencies

Project Flags

doku project add:

• --name, -n - Project name (defaults to directory name)
• --dockerfile - Path to Dockerfile (default: ./Dockerfile)
• --port, -p - Main port to expose
• --ports - Additional port mappings (host:container)
• --env, -e - Environment variables (KEY=VALUE)
• --depends - Service dependencies (e.g., postgres:16,redis)
• --domain - Custom domain (default: doku.local)
• --internal - Internal only (no Traefik/HTTPS)

doku project build:

• --no-cache - Build without using cache
• --pull - Pull base image before building
• --tag, -t - Custom tag for the image

doku project run:

• --build - Build image before running
• --install-deps - Automatically install missing dependencies
• --detach, -d - Run in background (default: true)

doku project remove:

• --image - Also remove the Docker image
• --yes, -y - Skip confirmation prompt

Uninstalling

To completely remove Doku from your system:

# Uninstall with confirmation prompt
doku uninstall

# Force uninstall without prompts
doku uninstall --force

# Uninstall and remove mkcert CA certificates
doku uninstall --all

What Gets Removed Automatically:

• ✅ All Docker containers managed by Doku
• ✅ All Docker volumes created by Doku
• ✅ Doku Docker network
• ✅ Configuration directory (~/.doku/)
• ✅ Doku binaries (doku and doku-cli)

Manual Cleanup (Optional):

The uninstall command provides OS-specific instructions for:

1. DNS entries - Remove *.doku.local entries from /etc/hosts or resolver
2. mkcert CA certificates - Optionally remove with mkcert -uninstall

Complete Removal:

# Run uninstall and immediately remove the binary
doku uninstall --force && rm -f ~/go/bin/doku ~/go/bin/doku-cli

Requirements

• Docker (Desktop or Engine)
• macOS, Linux, or Windows
• Ports 80 and 443 available

Development

# Clone the repository
git clone https://github.com/dokulabs/doku-cli
cd doku-cli

# Install dependencies
go mod download

# Build
make build

# Run
./bin/doku version

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

MIT License - see LICENSE for details.

Support

• 🐛 Report Issues
• 💬 Discussions

Made with ❤️ for developers who want a better local development experience.