Multi-Tenant Deployment (Flo CLI)

The Flo CLI manages multiple isolated tenants with blue-green deployments, automatic rollback, and encrypted secrets.

Overview

Each tenant gets:

• Isolated PostgreSQL database
• Separate Docker network
• Dedicated volumes
• Per-tenant .env file
• OIDC certificates
• AES-256-GCM encrypted secrets at rest

Traffic routing is handled by Traefik as a reverse proxy.

Installation

cd cli
npm install
npm link

# Verify
flo --help

Infrastructure Setup

# Initialize Traefik reverse proxy
flo traefik init

# Install SSL certificates
flo ssl install

Tenant Lifecycle

Create a Tenant

flo create api.customer.com

This provisions the full tenant stack: database, Docker containers, network, volumes, Traefik routing, and .env file.

Deploy

# Blue-green deploy with health check
flo deploy customer-tenant --image ghcr.io/team-ledges/flo:latest

Blue-green deployment process:

1. Pull new image
2. Start standby containers (green)
3. Run health checks
4. Switch Traefik routing from blue to green
5. Stop old containers (blue)
6. If health check fails → automatic rollback

Rollback

# Instant rollback to previous deployment
flo rollback customer-tenant

Monitor

flo list                     # List all tenants with health status
flo status customer-tenant   # Detailed tenant status
flo logs customer-tenant     # View logs
flo watchdog                 # Auto-restart unhealthy tenants
flo doctor                   # System health check

Backup & Restore

flo backup customer-tenant           # Create database backup
flo restore customer-tenant          # Restore from latest backup

Delete

flo delete customer-tenant           # Remove tenant (keeps data)
flo delete customer-tenant --data    # Remove tenant AND data

Full Command Reference

Command	Description
flo create <domain>	Create new tenant
flo deploy <tenant> --image <img>	Blue-green deploy
flo rollback <tenant>	Rollback to previous version
flo list	List all tenants with health
flo status <tenant>	Detailed tenant info
flo logs <tenant>	Stream logs
flo backup <tenant>	Database backup
flo restore <tenant>	Restore from backup
flo delete <tenant>	Remove tenant
flo watchdog	Auto-restart unhealthy tenants
flo doctor	System health check
flo traefik init	Initialize Traefik
flo ssl install	Install SSL certificates

Secrets Management

Tenant secrets (database passwords, API keys, OIDC certs) are encrypted at rest using AES-256-GCM. The CLI handles encryption/decryption transparently.

Architecture

Traefik (Reverse Proxy)
├── HTTPS → Tenant 1 (api.customer1.com)
│   ├── Flo App Container (blue)
│   ├── Flo App Container (green)  ← standby
│   └── PostgreSQL Database
├── HTTPS → Tenant 2 (api.customer2.com)
│   ├── Flo App Container (blue)
│   └── PostgreSQL Database
└── HTTPS → Tenant N
    └── ...

Each tenant is fully isolated: separate Docker network, database, and volumes. Traefik handles SSL termination and routing based on hostname.

Data Directory Structure

cli/data/
├── tenants/
│   ├── customer1/
│   │   ├── .env            # Encrypted tenant config
│   │   ├── docker-compose.yml
│   │   └── certs/          # OIDC certificates
│   └── customer2/
├── backups/
│   └── customer1/
│       └── 2026-02-27.sql.gz
└── traefik/
    ├── traefik.yml
    └── dynamic/