Getting Started

Installation

Complete guide to installing FlatRun Agent and UI on your server.

This guide covers the complete installation of both the FlatRun Agent and the web UI. For a minimal setup, see the Quick Start Guide.

System Requirements

Hardware

  • CPU: 1 core minimum, 2+ cores recommended
  • RAM: 1GB minimum, 2GB+ recommended
  • Disk: 10GB+ for system and Docker images

Software

  • OS: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+) or macOS
  • Docker: 20.10+ with Docker Compose v2
  • Permissions: Root or sudo access, Docker socket access

Install Docker

If Docker is not already installed:

# Install Docker using the official script
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group
sudo usermod -aG docker $USER

# Enable and start Docker
sudo systemctl enable --now docker

# Verify installation
docker --version
docker compose version

Install FlatRun Agent

Option 1: Download Binary (Recommended)

# Set architecture (amd64 or arm64)
ARCH="amd64"

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/flatrun/agent/releases/latest | grep '"tag_name"' | cut -d'"' -f4 | tr -d 'v')

# Download and extract
curl -LO https://github.com/flatrun/agent/releases/download/v$VERSION/flatrun-agent-$VERSION-linux-$ARCH.tar.gz
tar -xzf flatrun-agent-$VERSION-linux-$ARCH.tar.gz

# Install
sudo mv flatrun-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/flatrun-agent

# Verify
flatrun-agent --version

Option 2: Build from Source

# Requires Go 1.21+
git clone https://github.com/flatrun/agent.git
cd agent
go build -o flatrun-agent ./cmd/agent
sudo mv flatrun-agent /usr/local/bin/

Configure the Agent

Create the configuration file:

# Create directories
sudo mkdir -p /etc/flatrun
sudo mkdir -p /var/flatrun/deployments

# Generate a secure JWT secret
JWT_SECRET=$(openssl rand -base64 32)

# Create configuration
sudo tee /etc/flatrun/config.yml > /dev/null <<EOF
deployments_path: /var/flatrun/deployments

api:
  host: 0.0.0.0
  port: 8090
  enable_cors: true
  allowed_origins:
    - http://localhost:5173
    - https://your-domain.com

auth:
  enabled: true
  api_keys:
    - "$(openssl rand -hex 32)"
  jwt_secret: "$JWT_SECRET"

nginx:
  enabled: false

certbot:
  enabled: false
  email: admin@your-domain.com
  staging: true

logging:
  level: info
  format: json

infrastructure:
  default_proxy_network: proxy
  default_database_network: database
EOF

# Display the generated API key (save this!)
grep "api_keys:" -A1 /etc/flatrun/config.yml
Important: Save the generated API key securely. You'll need it to authenticate with the agent.

Set Up as System Service

# Create systemd service
sudo tee /etc/systemd/system/flatrun-agent.service > /dev/null <<EOF
[Unit]
Description=FlatRun Deployment Agent
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/flatrun-agent --config /etc/flatrun/config.yml
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable flatrun-agent
sudo systemctl start flatrun-agent

# Check status
sudo systemctl status flatrun-agent

Install FlatRun UI

Option 1: Pre-built Distribution

# Download the latest UI build from GitHub Actions
# Navigate to https://github.com/flatrun/ui/actions/workflows/ci.yml
# Download the dist artifact

# Extract to web root
sudo mkdir -p /var/www/flatrun-ui
sudo unzip dist.zip -d /var/www/flatrun-ui/

Option 2: Build from Source

# Requires Node.js 18+
git clone https://github.com/flatrun/ui.git
cd ui

# Install dependencies and build
npm install
npm run build

# Copy to web root
sudo mkdir -p /var/www/flatrun-ui
sudo cp -r dist/* /var/www/flatrun-ui/

Configure Nginx for UI

sudo tee /etc/nginx/sites-available/flatrun > /dev/null <<EOF
server {
    listen 80;
    server_name flatrun.your-domain.com;

    root /var/www/flatrun-ui;
    index index.html;

    # SPA routing
    location / {
        try_files \$uri \$uri/ /index.html;
    }

    # Proxy API requests to the agent
    location /api {
        proxy_pass http://localhost:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
        proxy_cache_bypass \$http_upgrade;
    }
}
EOF

# Enable the site
sudo ln -sf /etc/nginx/sites-available/flatrun /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Verify Installation

# Check agent health
curl http://localhost:8090/api/health

# Access the UI
# Open http://flatrun.your-domain.com in your browser
# Login with your API key

Next Steps