Installation

This guide will help you install Portoser on your system.

Prerequisites

Before installing Portoser, ensure you have:

  • Bash (version 4.0 or later)
  • SSH access to target machines
  • Docker (optional, for Docker-based services)
  • Python 3.12+ (optional, for web UI)

Installation

After obtaining Portoser:

# Navigate to the portoser directory
cd portoser

# Make the CLI executable
chmod +x portoser

# Add to PATH (optional)
sudo ln -s $(pwd)/portoser /usr/local/bin/portoser

Verify Installation

# Check that portoser is accessible
portoser --version

# View help
portoser --help

Optional: Install Web UI

The web UI provides a visual interface for managing your cluster.

Using Docker Compose (Recommended)

cd web

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
nano .env

# Start the web UI
docker-compose up -d

Using UV (Python Package Manager)

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up backend
cd web/backend
uv sync

# Set up frontend
cd ../frontend
npm install
npm run build

Optional: Install Dependencies

Depending on your use case, you may need additional tools:

For Docker-based Services

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

# Install Docker Compose
sudo apt-get install docker-compose-plugin  # Debian/Ubuntu
brew install docker-compose                  # macOS

For Vault Integration

# Install HashiCorp Vault
# See: https://developer.hashicorp.com/vault/install

For Caddy Integration

# Install Caddy
# See: https://caddyserver.com/docs/install

Configuration

Create Registry File

Create a registry.yml file to define your services and machines:

machines:
  m1:
    host: "192.168.0.245"
    user: "admin"
    platform: "darwin"

services:
  example-service:
    type: "docker"
    path: "/path/to/service"
    machine: "m1"

See the Registry Configuration guide for more details.

Set Up Environment Variables

Create a .env file in the portoser directory:

# Copy the example
cp .env.example .env

# Edit with your settings
nano .env

Key variables:

  • REGISTRY_FILE - Path to registry.yml
  • VAULT_ADDR - Vault server address (if using Vault)
  • LOG_LEVEL - Logging verbosity (DEBUG, INFO, WARN, ERROR)

Next Steps

Now that Portoser is installed:

  1. Quick Start Guide - Deploy your first service
  2. Core Concepts - Understand how Portoser works
  3. First Deployment - Step-by-step tutorial

Troubleshooting

Command Not Found

If you get "command not found" after installation:

# Check if portoser is in PATH
which portoser

# If not, add the directory to PATH
export PATH="$PATH:/path/to/portoser"

# Make permanent by adding to ~/.bashrc or ~/.zshrc
echo 'export PATH="$PATH:/path/to/portoser"' >> ~/.bashrc

Permission Denied

# Make sure the script is executable
chmod +x /path/to/portoser

# Check file permissions
ls -la /path/to/portoser

SSH Issues

Ensure you can SSH into target machines:

# Test SSH connection
ssh user@machine-host

# Set up SSH keys for passwordless auth (recommended)
ssh-copy-id user@machine-host

For more troubleshooting, see the Troubleshooting Guide.