iop

Commands

Complete reference for all iop CLI commands

Commands

Complete reference for all available iop CLI commands.

iop init

Initialize a new iop project with configuration files.

Usage

iop init [flags]

Flags

  • --help - Show help message
  • --non-interactive - Skip prompts, use defaults
  • --name <name> - Set project name (non-interactive mode)

Examples

iop init                    # Interactive setup
iop init --non-interactive  # Use defaults
iop init --name my-app      # Set name non-interactively

What it does

  • Creates iop.yml with configuration template
  • Creates .iop/secrets file for sensitive environment variables
  • Automatically adds .iop/secrets to .gitignore for security

Generated Files

iop.yml:

name: my-project

ssh:
  username: iop

apps:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    server: your-server-ip
    environment:
      plain:
        - NODE_ENV=production
      secret:
        - DATABASE_URL
    proxy:
      app_port: 3000
    health_check:
      path: /api/health

# Example service (uncomment and configure as needed)
# services:
#   db:
#     image: postgres:15
#     server: your-server-ip
#     ports:
#       - "5432:5432"
#     environment:
#       plain:
#         - POSTGRES_USER=postgres
#         - POSTGRES_DB=my-project
#       secret:
#         - POSTGRES_PASSWORD
#     volumes:
#       - ./pgdata:/var/lib/postgresql/data

.iop/secrets:

# Add your secret environment variables here
# Example:
# DATABASE_URL=postgres://user:password@localhost:5432/mydb
# POSTGRES_PASSWORD=supersecret
# API_KEY=your-api-key

iop (Deploy - Default Command)

Deploy applications and services to configured servers. This is the default command when no command is specified.

Usage

iop [entry-names...] [flags]       # Default - no 'deploy' needed
iop deploy [entry-names...] [flags] # Explicit command

Flags

  • --services - Deploy services only (skip apps)
  • --verbose - Show detailed deployment progress
  • --help - Show help message

Examples

iop                         # Deploy all apps and services
iop web api                 # Deploy specific apps/services
iop --services              # Deploy only services
iop --verbose               # Deploy with detailed output

Deployment Process

  1. Configuration validation - Load and validate iop.yml
  2. Git status check - Ensure working directory is clean
  3. Infrastructure setup - Automatically sets up servers if needed (no separate setup command required)
  4. Image building - Build Docker images locally for apps with build configuration
  5. Image transfer - Compress and transfer images via SSH (no registry needed)
  6. Zero-downtime deployment - Blue-green deployment for apps, direct replacement for services
  7. Health checks - Verify new versions are healthy before switching traffic
  8. Proxy configuration - Update reverse proxy routing

Example Output

 iop
Using Git SHA for release ID: a1b2c3d
Starting deployment with release a1b2c3d

[✓] Configuration loaded (0ms)
[✓] Git status verified (3ms)
[✓] Infrastructure ready (1.2s)

Building Images
  [✓] web my-app/web:a1b2c3d (45.2s)

Deploying to Servers
  └─ server1.com
     ├─ [✓] Loading image (3.2s)
     ├─ [✓] Zero-downtime deployment (2.8s)
     └─ [✓] Configuring proxy (0.8s)

[✓] Deployment completed successfully in 52.1s

Your apps are live at:
  └─ https://myapp.com (web)

Notes

  • Infrastructure setup is automatic (no separate setup command needed)
  • Commit git changes before deploying
  • Requires Docker running locally for image builds
  • App/service names cannot be: init, status, proxy (reserved)

iop status

Check deployment status across all servers with comprehensive information.

Usage

iop status [entry-names...] [flags]

Flags

  • --verbose - Show detailed status information
  • --help - Show help message

Examples

iop status                  # Check all deployments
iop status web              # Check specific app
iop status --verbose        # Detailed status info

Example Output

 iop status
📱 App: web
   Status: RUNNING (green active)
   Replicas: 1/1 running
   Image: my-app/web:a1b2c3d
   Servers: server1.com
   Last Deployed: 2 hours ago
   Uptime: 2h 15m
   Resource Usage: CPU 2.3%, Memory 125MB

🔧 Service: postgres
   Status: RUNNING
   Image: postgres:17
   Servers: server1.com
   Uptime: 1d 5h
   Resource Usage: CPU 0.8%, Memory 95MB

🔧 Proxy Status:
   server1.com: RUNNING (port 80, 443)
   - Version: elitan/iop-proxy:latest
   - Uptime: 1d 5h
   - Active routes: 2

Status Information

For each app/service, status shows:

  • Status - Current state (RUNNING, STOPPED, MIXED, UNKNOWN)
  • Active color - Which deployment slot is active (blue/green) for apps
  • Replicas - Number of running/desired replicas
  • Image - Current deployed image
  • Servers - Which servers are hosting the deployment
  • Last deployed - When the deployment occurred
  • Uptime - How long containers have been running
  • Resource usage - CPU and memory consumption

Detailed Status (--verbose)

With --verbose, you get additional information:

  • Exact image digests
  • Container restart counts
  • Exit codes (if applicable)
  • Port mappings
  • Volume mounts
  • Container health check details

iop proxy

Manage the iop reverse proxy that handles SSL and routing.

Usage

iop proxy <subcommand> [flags]

Subcommands

  • status - Show proxy status on all servers (default)
  • update - Update proxy to latest version on all servers
  • delete-host - Remove a host from proxy configuration
  • logs - Show proxy logs from all servers

Flags

  • --verbose - Show detailed output
  • --host <host> - Target specific host (for delete-host)
  • --lines <n> - Number of log lines to show (for logs, default: 50)

Examples

iop proxy status                              # Check status on all servers
iop proxy update --verbose                    # Update proxy with details
iop proxy delete-host --host api.example.com # Remove specific host
iop proxy logs --lines 100                   # Show last 100 log lines

iop proxy status

Shows the status of the iop proxy on all configured servers:

 iop proxy status

Proxy Statuses (2):

server1.com: RUNNING
- Container: iop-proxy
- Ports: 80, 443, 8080
- Image: elitan/iop-proxy:latest
- Uptime: 1d 5h
- Routes: 3 active

server2.com: RUNNING
- Container: iop-proxy
- Ports: 80, 443, 8080
- Image: elitan/iop-proxy:latest
- Uptime: 2h 30m
- Routes: 1 active

iop proxy update

Updates the proxy to the latest version on all servers:

 iop proxy update

server1.com
├─ [✓] Checking for updates
├─ [✓] Pulling latest image
├─ [✓] Updating proxy container
└─ [✓] Proxy updated successfully

Update Summary:
   Updated: 1 server(s)
   Skipped: 0 server(s) (already up to date)

iop proxy delete-host

Removes a specific host from the proxy configuration:

 iop proxy delete-host --host api.example.com

server1.com
└─ [✓] Host api.example.com deleted successfully

Deletion Summary:
   Deleted: 1 server(s)
   Not found: 0 server(s)

iop proxy logs

Shows recent logs from the proxy:

 iop proxy logs --lines 50

=== Proxy Logs from server1.com ===
2024-01-15 10:30:45 [INFO] Proxy server started on :80 and :443
2024-01-15 10:30:45 [INFO] API server started on :8080
2024-01-15 10:31:02 [INFO] Certificate obtained for myapp.com
2024-01-15 10:31:02 [INFO] Route configured: myapp.com -> localhost:3000
=== End logs from server1.com ===

Global Flags

These flags work with most commands:

--verbose

Show detailed output including:

  • SSH connection details
  • Docker command execution
  • Build progress
  • Deployment steps
  • Error diagnostics
iop --verbose
iop status --verbose
iop proxy status --verbose

--help

Show help information for any command:

iop --help              # Global help
iop init --help         # Command-specific help
iop proxy status --help # Subcommand help

Exit Codes

iop commands return standard exit codes:

  • 0 - Success
  • 1 - General error (configuration, network, deployment failure, etc.)

This makes iop suitable for use in CI/CD pipelines:

#!/bin/bash
iop
if [ $? -eq 0 ]; then
    echo "✅ Deployment successful"
else
    echo "❌ Deployment failed"
    exit 1
fi

Error Handling and Suggestions

iop provides helpful error messages with specific suggestions:

Configuration Errors

Error: Could not find iop.yml file

Suggestion:
   Run 'iop init' to create configuration files

SSH Connection Errors

Error: SSH connection failed to server.com

Suggestions:
   - Check server hostname in iop.yml
   - Verify SSH access to your servers
   - Use --verbose flag for detailed connection info

Docker Errors

Error: Docker build failed

Suggestions:
   - Ensure Docker is running locally
   - Check your Dockerfile syntax
   - Use --verbose flag for detailed build output

Git Status Errors

Error: Git working directory is not clean

Suggestions:
   - Commit your changes: git add . && git commit -m 'message'

For more help, use iop --help or iop <command> --help for command-specific information.