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

Configuration validation - Load and validate iop.yml
Git status check - Ensure working directory is clean
Infrastructure setup - Automatically sets up servers if needed (no separate setup command required)
Image building - Build Docker images locally for apps with build configuration
Image transfer - Compress and transfer images via SSH (no registry needed)
Zero-downtime deployment - Blue-green deployment for apps, direct replacement for services
Health checks - Verify new versions are healthy before switching traffic
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.

Commands

On this page