Quick Start

This guide will help you deploy your first application with FlatRun. We'll set up the agent, access the dashboard, and deploy a WordPress site as an example.

Prerequisites

• A Linux server (Ubuntu 20.04+ recommended) or macOS
• Docker and Docker Compose installed
• Root or sudo access

Step 1: Install the Agent

Download and install the FlatRun Agent binary:

# Download the latest release
VERSION=$(curl -s https://api.github.com/repos/flatrun/agent/releases/latest | grep '"tag_name"' | cut -d'"' -f4 | tr -d 'v')
curl -LO https://github.com/flatrun/agent/releases/download/v$VERSION/flatrun-agent-$VERSION-linux-amd64.tar.gz

# Extract and install
tar -xzf flatrun-agent-$VERSION-linux-amd64.tar.gz
sudo mv flatrun-agent /usr/local/bin/

# Verify installation
flatrun-agent --version

Step 2: Create Configuration

Create a configuration file for the agent:

# Create config directory
sudo mkdir -p /etc/flatrun

# Create configuration file
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
    - http://localhost:3000

auth:
  enabled: true
  api_keys:
    - "your-secure-api-key-here"
  jwt_secret: "$(openssl rand -base64 32)"

logging:
  level: info
  format: json
EOF

# Create deployments directory
sudo mkdir -p /var/flatrun/deployments

Step 3: Start the Agent

Run the agent directly or set it up as a service:

# Run directly (for testing)
flatrun-agent --config /etc/flatrun/config.yml

# Or set up as a 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
ExecStart=/usr/local/bin/flatrun-agent --config /etc/flatrun/config.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

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

Step 4: Access the Dashboard

The agent's API is now running on port 8090. To access the web dashboard, you can either:

• Option A: Deploy the UI alongside the agent (see Installation Guide)
• Option B: Use the API directly with curl or any HTTP client

Step 5: Deploy Your First App

Let's deploy a WordPress site using the API:

# Authenticate and get a token
TOKEN=$(curl -s -X POST http://localhost:8090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-secure-api-key-here"}' | jq -r '.token')

# List available templates
curl -s http://localhost:8090/api/templates \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | .id'

# Create a WordPress deployment
curl -X POST http://localhost:8090/api/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-wordpress",
    "template_id": "wordpress",
    "auto_start": true
  }'

Your WordPress site is now running! Access it at the container's port (default: 8080).

What's Next?

• Full Installation Guide — Detailed setup including the UI
• Understanding Deployments — Learn how deployments work
• Available Templates — See all pre-built templates
• Configuration Reference — Full configuration options