otterstack-usage

What this skill does

# OtterStack Usage Guide

Complete reference for using OtterStack - a deployment orchestration tool for Docker Compose applications with zero-downtime deployments via Traefik priority-based routing.

## What is OtterStack?

OtterStack is a **Git-driven deployment orchestrator** for Docker Compose applications running on a single VPS. It provides:

- **Zero-downtime deployments** using Traefik priority-based routing
- **Git worktree isolation** - each deployment gets its own directory
- **Health check validation** before traffic switching
- **Automatic rollback** if deployments fail
- **Environment variable management** with smart type detection
- **Deployment history** and retention policies

### Core Concepts

1. **Projects**: A project is a Docker Compose application tracked in git
2. **Worktrees**: Each deployment creates an isolated git worktree
3. **Deployments**: Deploy any git ref (commit, branch, tag)
4. **Priority Routing**: New containers start at priority 200, old at 100
5. **Health Checks**: Validates containers before traffic switch (5 min timeout)

## Installation

```bash
go build ./cmd/otterstack
./otterstack version
```

## Quick Start

### 1. Add Your First Project

**Local repository:**
```bash
otterstack project add myapp /srv/myapp
```

**Remote repository:**
```bash
otterstack project add myapp https://github.com/user/repo.git
```

**With Traefik zero-downtime routing:**
```bash
otterstack project add myapp https://github.com/user/repo.git --traefik-routing
```

**Custom compose file:**
```bash
otterstack project add myapp /srv/myapp --compose-file docker-compose.prod.yml
```

### 2. Configure Environment Variables

OtterStack now has **smart environment variable management** with auto-discovery!

**Option 1: Auto-discovery during project add**
```bash
# Create .env.<project-name> in current directory
echo "DATABASE_URL=postgres://localhost/mydb" > .env.myapp
echo "API_KEY=secret123" >> .env.myapp

# Add project - OtterStack will auto-discover and load the file
otterstack project add myapp /srv/myapp

# Prompts interactively for any missing variables
```

**Option 2: Set variables manually**
```bash
otterstack env set myapp DATABASE_URL=postgres://localhost/mydb
otterstack env set myapp API_KEY=secret DEBUG=false
```

**Option 3: Load from file**
```bash
otterstack env load myapp .env.production
```

**Option 4: Interactive scan (for existing projects)**
```bash
otterstack env scan myapp
# Scans compose file, prompts for missing variables
```

**List variables:**
```bash
otterstack env list myapp
otterstack env list myapp --show-values  # Show actual values
```

**Get specific variable:**
```bash
otterstack env get myapp DATABASE_URL
```

**Remove variables:**
```bash
otterstack env unset myapp DEBUG
```

### 3. Deploy

**Deploy default branch:**
```bash
otterstack deploy myapp
```

**Deploy specific ref:**
```bash
otterstack deploy myapp --ref feature/new-ui
otterstack deploy myapp --ref v1.2.3
otterstack deploy myapp --ref a1b2c3d4
```

**Force deploy (skip validations - use carefully!):**
```bash
otterstack deploy myapp --force
```

### 4. Check Status

**List all projects:**
```bash
otterstack project list
```

**View project details:**
```bash
otterstack status myapp
```

**Check deployment history:**
```bash
otterstack deployments myapp
```

### 5. Manage Projects

**Remove project:**
```bash
otterstack project remove myapp
```

**Force remove (skip confirmation):**
```bash
otterstack project remove myapp --force
```

## Environment Variable Management

### Smart Type Detection

OtterStack automatically detects variable types from names:

| Pattern | Type | Validation |
|---------|------|------------|
| `DATABASE_URL`, `API_ENDPOINT` | URL | Must have scheme (https://) |
| `ADMIN_EMAIL`, `SUPPORT_EMAIL` | Email | Valid email format |
| `HTTP_PORT`, `DB_PORT` | Port | 1-65535 |
| `WORKER_COUNT`, `MAX_CONNECTIONS`, `TIMEOUT` | Integer | Valid number |
| `DEBUG_ENABLED`, `FEATURE_FLAG`, `USE_SSL` | Boolean | Yes/No dialog |
| Everything else | String | Basic validation |

### Interactive Prompts

When you run `env scan` or `project add`, OtterStack:

1. **Parses compose file** to find all `${VAR}` references
2. **Checks stored values** to identify missing variables
3. **Groups prompts**: Required first, optional second
4. **Type-aware UI**: Booleans use Yes/No dialogs, others use validated text inputs
5. **Shows context**: "Used by: web, worker"
6. **Generates `.env.example`** for documentation

### Supported Variable Formats

OtterStack parses these Docker Compose formats:

```yaml
services:
  web:
    environment:
      - DATABASE_URL=${DATABASE_URL}              # Required
      - API_URL=${API_URL:-https://api.example.com}  # Optional with default
      - SECRET_KEY=${SECRET_KEY:?Secret key required}  # Required with error message
      - DEBUG=$DEBUG                              # Simple form
```

## Zero-Downtime Deployments with Traefik

### Prerequisites

1. **Traefik running** and connected to Docker
2. **Compose file has Traefik labels:**

```yaml
services:
  web:
    image: myapp:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.web.rule=Host(`myapp.example.com`)"
```

3. **Project added with `--traefik-routing` flag**

### How It Works

```
1. [Old Containers Serving] → Priority: 100

2. [Start New Containers] → No Traefik labels yet

3. [Health Check] → Wait up to 5 minutes

4. [Apply Priority Labels] → New: 200, Old: 100

5. [Traffic Switches] → Traefik routes to higher priority

6. [Stop Old Containers] → Deployment complete
```

If health checks fail at step 3, old containers keep serving traffic.

### Deployment Flow

**Without Traefik:**
- Start new containers
- Stop old containers immediately
- Brief downtime during switch

**With Traefik:**
- Start new containers (no traffic)
- Wait for healthy
- Switch traffic priority
- Stop old containers
- Zero downtime!

## Command Reference

### Project Management

```bash
# Add project
otterstack project add <name> <repo-path-or-url> [flags]
  --compose-file string    Path to compose file (default: docker-compose.yml)
  --traefik-routing        Enable zero-downtime Traefik routing

# List projects
otterstack project list

# Remove project
otterstack project remove <name> [--force]

# View project status
otterstack status <name>
```

### Environment Variables

```bash
# Set variables
otterstack env set <project> KEY=VALUE [KEY=VALUE...]

# Get variable
otterstack env get <project> [KEY]

# List variables
otterstack env list <project> [--show-values]

# Load from file
otterstack env load <project> <file>

# Interactive scan
otterstack env scan <project>

# Remove variables
otterstack env unset <project> KEY [KEY...]
```

### Deployment

```bash
# Deploy
otterstack deploy <project> [flags]
  --ref string     Git ref to deploy (commit, branch, tag)
  --force          Skip validation checks

# View deployment history
otterstack deployments <project>
```

### Global Flags

```bash
--config string    Config file (default: $HOME/.otterstack.yaml)
--data-dir string  Data directory (default: $HOME/.otterstack)
--verbose          Verbose output
--help            Show help
--version         Show version
```

## Common Workflows

### First-Time Project Setup

```bash
# 1. Create .env file
cat > .env.myapp <<EOF
DATABASE_URL=postgres://user:pass@localhost/mydb
REDIS_URL=redis://localhost:6379
API_KEY=your-secret-key
EOF

# 2. Add project (auto-discovers .env.myapp)
otterstack project add myapp https://github.com/user/repo.git --traefik-routing

# 3. Verify configuration
otterstack env list myapp

# 4. Deploy
otterstack deploy myapp
```

### Adding Variables to Existing Project

```bash
# Option 1: Interactive scan
otterstack env scan myapp

# Option 2: Manual set
otterstack env set myapp NEW_VAR=value

# Option 3: Load from file
otterstack env load myapp .env.new
```

### Deploying a Feature Branch

```bash
# Deploy feature branch
otterstack deploy