tako-cli

README

🐙 Tako CLI

タコ - Deploy your applications to any VPS with zero configuration and zero downtime.

What is Tako?

Tako (タコ) is Japanese for "octopus" - pronounced "tah-koh". Just like an octopus has 8 arms to manage multiple tasks simultaneously, Tako CLI manages your deployments across multiple servers with precision and control.

Tako CLI is a powerful deployment automation tool that brings Platform-as-a-Service (PaaS) simplicity to your own infrastructure. Deploy Docker containers to your VPS servers with automatic HTTPS, health checks, zero-downtime deployments, and complete control over your infrastructure.

Note: This is a personal pet project built by Redentor Valerio (@redentor_dev) for my own use. Feel free to use it, but I provide no liability or guarantees. See License for details.

---

Why Tako CLI?

Tako CLI brings PaaS-like simplicity with full infrastructure control - deploy to your own servers without vendor lock-in or monthly fees.

Key Benefits

• Deploy in minutes, not hours or days
• Use your own servers (DigitalOcean, Hetzner, AWS EC2, any VPS)
• Zero-downtime deployments with automatic rollback
• Automatic HTTPS certificates (Let's Encrypt + Traefik)
• Git-based deployments with full version history
• No monthly PaaS fees - pay only for your server
• Multi-server orchestration with Docker Swarm
• Cross-project service networking

---

Quick Start

Installation

One-line install (Linux & macOS):

curl -fsSL https://raw.githubusercontent.com/redentordev/tako-cli/master/install.sh | bash

Alternative installation methods

Manual Download

Linux (AMD64):

curl -L https://github.com/redentordev/tako-cli/releases/latest/download/tako-linux-amd64 -o /usr/local/bin/tako
chmod +x /usr/local/bin/tako

Linux (ARM64):

curl -L https://github.com/redentordev/tako-cli/releases/latest/download/tako-linux-arm64 -o /usr/local/bin/tako
chmod +x /usr/local/bin/tako

macOS (Intel):

curl -L https://github.com/redentordev/tako-cli/releases/latest/download/tako-darwin-amd64 -o /usr/local/bin/tako
chmod +x /usr/local/bin/tako

macOS (Apple Silicon):

curl -L https://github.com/redentordev/tako-cli/releases/latest/download/tako-darwin-arm64 -o /usr/local/bin/tako
chmod +x /usr/local/bin/tako

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/redentordev/tako-cli/releases/latest/download/tako-windows-amd64.exe" -OutFile "tako.exe"
# Add to your PATH

Build from Source

Requires Go 1.21+

git clone https://github.com/redentordev/tako-cli.git
cd tako-cli
make build

Deploy Your First App (5 minutes)

1. Initialize your project:

tako init my-app

This creates:

• tako.yaml - Deployment configuration with comprehensive examples
• .env.example - Environment variables template
• .gitignore - Git ignore rules

1. Configure your environment:

Copy .env.example to .env and set your values:

cp .env.example .env

Edit .env:

SERVER_HOST=203.0.113.10              # Your VPS IP
LETSENCRYPT_EMAIL=admin@example.com   # For SSL certificates

1. Review and customize tako.yaml:

The generated tako.yaml includes a working web service example:

project:
  name: my-app
  version: 1.0.0

servers:
  production:
    host: ${SERVER_HOST}
    user: root
    sshKey: ~/.ssh/id_ed25519

environments:
  production:
    servers: [production]
    services:
      web:
        build: .                                      # Build from current directory
        port: 3000                                    # Container port
        proxy:
          domains:
            - my-app.${SERVER_HOST}.sslip.io         # Auto-DNS with sslip.io
          email: ${LETSENCRYPT_EMAIL}
        env:
          NODE_ENV: production

The template includes commented examples for:

• Database services (PostgreSQL, Redis)
• Background workers
• Health checks and lifecycle hooks
• Secrets management
• Multi-server deployments
• And more!

1. Setup your server (one-time):

tako setup -e production

This installs Docker, Traefik, configures firewall, and hardens security.

1. Deploy your application:

tako deploy -e production

Your app is now live with automatic HTTPS at https://my-app.YOUR-SERVER-IP.sslip.io!

---

Features

Deployment & Operations

• Zero-Downtime Deployments - Blue-green strategy with automatic health checks
• Parallel Deployment - Deploy multiple services concurrently (default behavior)
• Instant Rollback - Revert to any previous deployment with one command
• Git-Based Versioning - Every deployment tied to a Git commit
• State Management - Full deployment history tracked on server
• Automatic HTTPS - Traefik provisions SSL certificates via Let's Encrypt
• Health Checks - Ensure containers are healthy before switching traffic
• Secrets Management - Secure handling of environment secrets with automatic redaction
• Lifecycle Hooks - Automate tasks at build, deploy, and start phases (migrations, cache warming, etc.)

Infrastructure & Scaling

• Multi-Server Support - Deploy to multiple servers simultaneously
• Docker Swarm Integration - Automatic orchestration for 2+ servers
• Placement Strategies - Control service placement (spread, pinned, any)
• Cross-Project Networking - Services communicate across projects
• Service Discovery - Built-in DNS and load balancing
• Server Provisioning - One-command setup with security hardening

Developer Experience

• Simple YAML Configuration - Intuitive and readable
• Environment Variables - Full support with .env files
• Local Development Mode - Run production environment locally with tako dev
• Auto-Update - Built-in upgrade mechanism with tako upgrade
• Verbose Logging - Detailed output for debugging
• Cross-Platform - Single binary for Windows, macOS, Linux
• No Dependencies - Just the binary and SSH access

---

Core Commands

Deployment & Management

Command	Description
tako init	Initialize new project with template config
tako setup	Provision server (Docker, Traefik, security hardening)
tako deploy	Deploy application to environment
tako rollback [id]	Rollback to previous/specific deployment
tako destroy	Remove all services from server

Operations & Monitoring

Command	Description
tako ps	List running services and their status
tako logs	Stream container logs
tako access	Stream access logs from Traefik (HTTP requests)
tako metrics	View system metrics from servers
tako monitor	Continuously monitor deployed services
tako history	View deployment history

Service Control

Command	Description
tako start	Start stopped services
tako stop	Stop running services
tako scale	Scale service replicas
tako exec	Execute commands on remote server(s)

Secrets Management

Command	Description
tako secrets init	Initialize secrets storage for project
tako secrets set <KEY>=<value>	Set a secret value
tako secrets list	List all secrets (redacted)
tako secrets delete <KEY>	Delete a secret
tako secrets validate	Validate all required secrets are set

Development & Utilities

Command	Description
tako upgrade	Upgrade Tako CLI to the latest version
tako dev	Run production environment locally
tako live	Live development mode with hot reload
tako cleanup	Clean up old Docker resources
tako downgrade	Downgrade from Docker Swarm to single-server mode

Common Flags

• -v, --verbose - Show detailed output
• -e, --env <name> - Target specific environment
• -s, --server <name> - Target specific server
• --service <name> - Target specific service
• --config <path> - Use custom config file

---

Configuration Examples

Simple Web Application

services:
  web:
    build: .
    port: 3000
    env:
      NODE_ENV: production
    proxy:
      domains:
        - app.example.com
      email: admin@example.com

Full-Stack Application

services:
  web:
    build: ./frontend
    port: 3000
    proxy:
      domains:
        - app.example.com

  api:
    build: ./backend
    port: 4000
    replicas: 2
    env:
      DATABASE_URL: postgresql://db:5432/myapp

  database:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data
    env:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Multi-Server with Docker Swarm

servers:
  server1:
    host: ${SERVER1_HOST}
  server2:
    host: ${SERVER2_HOST}

environments:
  production:
    servers: [server1, server2]
    services:
      web:
        build: .
        port: 3000
        replicas: 4
        placement:
          strategy: spread  # Distribute across all servers

Background Workers

services:
  worker:
    build: ./worker
    replicas: 3
    env:
      REDIS_URL: redis://redis:6379
    # No port = background service

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

Secrets Management

services:
  api:
    build: .
    port: 3000
    env:
      NODE_ENV: production
    secrets:
      - DATABASE_URL           # Secret from .tako/secrets
      - JWT_SECRET
      - API_KEY:STRIPE_KEY    # Alias: container sees API_KEY, reads STRIPE_KEY

Usage:

# Initialize secrets storage
tako secrets init

# Set secrets per environment
tako secrets set DATABASE_URL=postgresql://... --env production
tako secrets set JWT_SECRET=super-secret-token --env production

# List secrets (redacted)
tako secrets list --env production

# Deploy with secrets
tako deploy --env production

Lifecycle Hooks

Automate tasks at different deployment phases - perfect for migrations, cache warming, or notifications:

services:
  api:
    build: .
    port: 3000
    hooks:
      preBuild:
        - "npm run generate-types"      # Run before building
      postBuild:
        - "docker scan {{IMAGE}}"        # Security scan after build
      preDeploy:
        - "curl https://api.slack.com/..." # Notify team
      postDeploy:
        - "echo 'Deployed successfully!'"
      postStart:
        - "exec: npm run migrate"        # Run migrations inside container
        - "exec: npm run seed"           # Seed database

Hook Types:

1. Shell Commands - Run on the server

   - "echo 'Starting deployment'"
   - "curl -X POST https://webhook.com/notify"
   

2. Container Commands - Run inside the container (use exec: prefix)

   - "exec: npm run migrate"
   - "exec: php artisan cache:clear"
   - "exec: python manage.py migrate"
   

Available Lifecycle Phases:

• preBuild - Before building Docker image
• postBuild - After building Docker image (use {{IMAGE}} placeholder)
• preDeploy - Before deploying service
• postDeploy - After deploying service
• postStart - After service is running (best for migrations)

Common Use Cases:

# Database migrations
postStart:
  - "exec: npm run migrate"

# Cache warming
postStart:
  - "exec: php artisan cache:warm"

# Deployment notifications
postDeploy:
  - "curl -X POST https://hooks.slack.com/... -d 'Deployed!'"

# Security scanning
postBuild:
  - "docker scan {{IMAGE}}"

See the Plausible example for a real-world use case.

Parallel Deployment (Default)

Tako CLI deploys services in parallel by default for faster deployments. You can customize this behavior:

project:
  name: my-app
  version: 1.0.0

# Optional: Customize parallel deployment (these are the defaults)
deployment:
  strategy: parallel  # or "sequential"
  parallel:
    maxConcurrentBuilds: 4   # Max builds at once
    maxConcurrentDeploys: 4  # Max deploys at once
  cache:
    enabled: true     # Enable build caching
    type: local       # Cache type

Benefits:

• Faster deployments for multi-service apps
• Dependency-aware scheduling
• Automatic build caching
• Concurrent builds and deploys

---

Architecture

Single-Server Mode

┌─────────────────┐
│   Tako CLI      │
│  (Local)        │
└────────┬────────┘
         │ SSH
         ▼
┌─────────────────┐
│   VPS Server    │
├─────────────────┤
│ Traefik (HTTPS) │
│ Docker Engine   │
│ Your Containers │
│ State Storage   │
└─────────────────┘

Multi-Server Swarm Mode

    Tako CLI
        │
   ┌────┴────┬────────┐
   │         │        │
Manager    Worker1  Worker2
   │         │        │
Registry  Services Services
Traefik   Replicas Replicas
   └─── Overlay Network ───┘

---

Examples

Check out the examples/ directory for ready-to-deploy projects:

Web Frameworks & Applications

• 01-simple-web - Basic Node.js web application
• 02-web-database - Web app with PostgreSQL
• 03-fullstack - Frontend + backend + database
• 04-monorepo - Multiple services in one repo
• 09-nextjs-todos - Next.js with SQLite
• 12-hono - Hono (ultra-fast Edge framework)
• 13-sveltekit - SvelteKit (full-stack Svelte)
• 14-solidstart - SolidStart (fine-grained reactivity)
• 15-astro - Astro (content-driven framework)
• 16-php - Vanilla PHP 8.3 application
• 17-laravel - Laravel (PHP framework)
• 18-rails - Ruby on Rails application

Scaling & Infrastructure

• 05-workers - Background job processing
• 06-scaling - Multi-replica deployment
• 07-backend-api - RESTful API service
• 08-frontend-consumer - Frontend consuming external API
• 11-multi-server-swarm - Multi-server orchestration

Third-Party Applications

• 17-n8n - n8n (workflow automation)
• 18-plausible - Plausible (web analytics)
• 19-umami - Umami (web analytics)
• 20-ghost - Ghost (headless CMS)

Testing & Advanced

• test-parallel - Parallel deployment testing
• test-placement-strategies - Swarm placement strategies
• test-secrets - Secrets management
• test-swarm - Docker Swarm testing

Each example includes complete documentation and is ready to deploy.

---

Development

Prerequisites

• Go 1.21 or higher
• Git
• Docker (for local testing)
• Make (optional)

Building from Source

# Clone repository
git clone https://github.com/redentordev/tako-cli.git
cd tako-cli

# Install dependencies
go mod download

# Build binary
go build -o tako .

# Or use Makefile
make build

# Build for all platforms
make build-all

Project Structure

tako-cli/
├── cmd/                  # CLI commands (23 commands)
│   ├── deploy.go         # Deployment logic
│   ├── setup.go          # Server provisioning
│   ├── rollback.go       # Rollback functionality
│   ├── access.go         # Traefik access logs
│   ├── monitor.go        # Service monitoring
│   └── ...               # Other commands
├── pkg/                  # Reusable packages
│   ├── config/           # Configuration management
│   ├── deployer/         # Core deployment engine
│   ├── swarm/            # Docker Swarm orchestration
│   ├── traefik/          # Traefik reverse proxy
│   ├── git/              # Git operations
│   ├── ssh/              # SSH client with pooling
│   ├── provisioner/      # Server setup
│   ├── monitoring/       # Service health monitoring
│   ├── accesslog/        # Access log formatting
│   └── ...               # Other packages
├── internal/             # Internal packages
│   └── state/            # Deployment state management
├── examples/             # Example projects (25 examples)
├── docs/                 # Documentation
└── Makefile              # Build automation

---

Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

License

MIT License - see LICENSE file for full text.

⚠️ Disclaimer: This is a personal pet project. While functional, it comes with no guarantees or liability. Use at your own risk.

---

Acknowledgments

Tako CLI is inspired by the excellent work of:

• Kamal by DHH and 37signals
• Dokku by Jeff Lindsay
• Docker Swarm by Docker Inc.
• The simplicity of Heroku's developer experience

---

🐙 Built by Redentor Valerio (@redentor_dev) | Start deploying in minutes, not hours. Your servers, your rules.