Installation

Get iop up and running on your system.

Prerequisites

Local Machine

• Node.js 18+ - For running the iop CLI
• Git - For version tracking and release IDs
• Docker - Required for building app images locally

Target Servers

• Ubuntu/Debian Linux - iop supports Ubuntu and Debian-based distributions
• SSH access - iop needs to connect and set up infrastructure
• Ports 22, 80, and 443 open - For SSH, HTTP, and HTTPS traffic

Install iop CLI

Using npm (Recommended)

npm install -g iop

Using npx (No Installation)

You can run iop without installing it globally:

npx iop init
npx iop

Verify Installation

Check that iop is installed correctly:

iop --help

You should see output similar to:

iop CLI - Zero-downtime Docker deployments
================================================

USAGE:
  iop [flags]                 # Deploy (default action)
  iop <command> [flags]       # Run specific command

COMMANDS:
  init      Initialize iop.yml config and secrets file
  status    Check deployment status across all servers
  proxy     Manage iop proxy (status, update)

GLOBAL FLAGS:
  --help     Show command help
  --verbose  Show detailed output

EXAMPLES:
  iop init                    # Initialize new project
  iop                         # Deploy all apps and services
  iop --verbose               # Deploy with detailed output
  iop status                  # Check all deployments
  iop proxy status            # Check proxy status

Server Preparation (Optional)

iop automatically sets up servers during deployment, but you can prepare them in advance:

Create a Deployment User (Recommended)

For better security, create a dedicated user for deployments:

# On your server
sudo useradd -m -s /bin/bash iop
sudo usermod -aG docker,sudo iop

# Set up SSH key access
ssh-copy-id iop@your-server.com

Then configure iop to use this user:

# iop.yml
ssh:
  username: iop

Manual Docker Installation (Optional)

iop will install Docker automatically, but you can install it manually:

# On Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Network Configuration

Ensure your servers have the required ports open:

• Port 22 - SSH access for iop
• Port 80 - HTTP traffic (redirected to HTTPS)
• Port 443 - HTTPS traffic
• Port 8080 - iop proxy API (localhost only)

Firewall Configuration

iop automatically configures firewall rules, but you can set them up manually:

# On Ubuntu/Debian with ufw
sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP
sudo ufw allow 443/tcp  # HTTPS
sudo ufw enable

Docker Configuration

iop requires Docker to be running locally for building images:

macOS (Docker Desktop)

1. Download and install Docker Desktop
2. Start Docker Desktop
3. Verify: docker --version

Linux

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Add your user to docker group (avoid sudo)
sudo usermod -aG docker $USER

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Verify installation
docker --version

Windows

1. Install Docker Desktop for Windows
2. Enable WSL 2 backend if prompted
3. Verify: docker --version

Next Steps

With iop installed, you're ready to:

1. Initialize your first project - iop init
2. Configure your deployment - Edit iop.yml
3. Deploy your application - iop

Troubleshooting

Command Not Found

If you get command not found after installation:

1. Restart your terminal - Close and reopen your terminal
2. Check your PATH - Make sure npm global bin directory is in your PATH:

npm config get prefix
# Add the bin directory to your PATH if needed
export PATH=$(npm config get prefix)/bin:$PATH

3. Use npx - Run npx iop as an alternative

Permission Issues

If you encounter permission issues during installation:

1. Don't use sudo with npm install - This can cause permission problems
2. Configure npm to avoid sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3. Use a Node version manager - Consider using nvm, fnm, or volta

Docker Issues

If Docker is not working:

1. Verify Docker is running: docker --version
2. Check Docker daemon: docker ps
3. Add to docker group: sudo usermod -aG docker $USER (then logout/login)

SSH Connection Issues

If iop cannot connect to your servers:

1. Test SSH manually: ssh user@your-server.com
2. Check SSH key authentication: ssh -i ~/.ssh/id_rsa user@your-server.com
3. Verify server hostname/IP in iop.yml
4. Use verbose mode: iop --verbose for detailed connection info

Node.js Version Issues

iop requires Node.js 18+. Check your version:

node --version

If you need to upgrade:

Using nvm (recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Using package manager:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS with Homebrew
brew install node@18

Development Setup

If you want to contribute to iop or run it from source:

# Clone the repository
git clone https://github.com/elitan/iop.git
cd iop

# Install dependencies
bun install

# Build the CLI
bun run build

# Link for local development
cd packages/cli
bun link

# Now you can use `iop` anywhere
iop --help

This will build the CLI from source and make it available globally on your system.