Getting Started

Installation

Complete guide to installing FlatRun on your server.

FlatRun can be installed with a single command using our installer script, or manually if you prefer full control over the process.

System Requirements

Hardware

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

Software

  • OS: Ubuntu 20.04+, Debian 11+
  • Permissions: Root or sudo access

Automated Installation (Recommended)

The installer script handles everything: Docker, the FlatRun Agent, the web UI, reverse proxy, firewall rules, and systemd service configuration. 

curl -fsSL https://raw.githubusercontent.com/flatrun/installer/main/scripts/install.sh | sudo bash

Once complete, open your browser to finish setup:

http://YOUR_SERVER_IP:8080/setup
What the installer does:
  • Installs Docker and Docker Compose (if not present)
  • Downloads the latest FlatRun Agent binary
  • Deploys the web UI as a Docker container on port 8080
  • Configures Nginx reverse proxy via Docker
  • Sets up the agent as a systemd service
  • Configures UFW firewall rules
  • Generates a secure JWT secret and API key

Cloud Images

FlatRun is also available as pre-built cloud images on DigitalOcean and AWS. These are ready to launch with everything pre-installed — just create the droplet/instance and visit the setup page.

Manual Installation

If you prefer to install each component yourself, follow the steps below.

1. Install Docker

# 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

2. Install FlatRun Agent

Download Binary

# 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

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/

3. Configure the Agent

# Create directories
sudo mkdir -p /etc/flatrun
sudo mkdir -p /opt/flatrun/bin /opt/flatrun/deployments

# Generate secrets
JWT_SECRET=$(openssl rand -base64 32)
API_KEY=$(openssl rand -hex 32)

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

api:
  host: 0.0.0.0
  port: 8090
  enable_cors: true
  allowed_origins:
    - http://localhost:8080

auth:
  enabled: true
  api_keys:
    - "$API_KEY"
  jwt_secret: "$JWT_SECRET"

nginx:
  enabled: false

certbot:
  enabled: false
  email: [email protected]
  staging: true

logging:
  level: info
  format: json

infrastructure:
  default_proxy_network: proxy
  default_database_network: database
EOF

echo "Your API key: $API_KEY"
Important: Save the generated API key securely. You'll need it to authenticate with the agent.

4. Set Up as System 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

sudo systemctl daemon-reload
sudo systemctl enable --now flatrun-agent
sudo systemctl status flatrun-agent

5. Deploy the UI

The UI runs as a Docker container with built-in API proxying:

# Create UI deployment directory
sudo mkdir -p /opt/flatrun/deployments/ui

# Create docker-compose.yml
sudo tee /opt/flatrun/deployments/ui/docker-compose.yml > /dev/null <<EOF
services:
  ui:
    image: ghcr.io/flatrun/ui:latest
    container_name: flatrun-ui
    restart: unless-stopped
    ports:
      - "8080:80"
    extra_hosts:
      - "host.docker.internal:host-gateway"
EOF

# Start the UI
docker compose -f /opt/flatrun/deployments/ui/docker-compose.yml up -d

6. Deploy Nginx Reverse Proxy

# Use the agent's built-in infrastructure setup
flatrun-agent setup infra nginx --config /etc/flatrun/config.yml

7. Verify Installation

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

# Access the UI at
# http://YOUR_SERVER_IP:8080/setup

Next Steps

Star us on GitHub