Skip to main content

​
Overview

Deploy Metlo on any machine with Docker and Docker Compose. This is the quickest way to get started with Metlo and requires minimal setup.

​
Prerequisites

  • Docker Engine installed
  • Docker Compose (v1.29.0 or later)
  • At least 4GB of RAM
  • 10GB of available disk space

​
Quick Start

1

Install deployment script

Download and install the Metlo deployment management script:
sudo mkdir -p /opt/metlo
sudo wget https://raw.githubusercontent.com/metlo-labs/metlo/master/manage-deployment.py -O /opt/metlo/manage-deployment.py
sudo chmod +x /opt/metlo/manage-deployment.py
sudo ln -s /opt/metlo/manage-deployment.py /usr/bin/metlo-deploy
2

Initialize Metlo

Initialize the Metlo deployment (pulls required files and Docker images):
export METLO_DIR=/opt/metlo
sudo -E metlo-deploy init
You’ll be prompted for an optional license key. Press Enter to skip for the open-source version.
3

Start Metlo

Start all Metlo services:
sudo metlo-deploy start
4

Access the dashboard

Once started, access the Metlo dashboard:
  • Frontend UI: http://YOUR_SERVER_IP:8000
  • Backend API: http://YOUR_SERVER_IP:8080
  • Collector (Ingestor): http://YOUR_SERVER_IP:8081

​
Architecture

The Docker deployment consists of six services:
  • PostgreSQL Database (db) - Stores all API security data
  • Redis Cache (cache) - Handles session management and caching
  • Ingestor (ingestor) - Collects and processes API traffic data
  • Backend (backend) - Core API and business logic
  • Jobs Runner (jobs) - Handles background processing tasks
  • Analyzer (analyzer) - Analyzes API traffic for security issues
  • Frontend (frontend) - Web UI for the dashboard

​
Environment Variables

Metlo uses environment variables for configuration. These are automatically generated during initialization and stored in /opt/metlo/.env:

​
Required Variables

​
ENCRYPTION_KEY
string
required
Base64-encoded encryption key for sensitive data. Auto-generated during setup.
​
BACKEND_URL
string
required
URL where the backend service is accessible (e.g., http://YOUR_IP:8081)
​
EXPRESS_SECRET
string
required
Secret key for Express.js session management. Auto-generated during setup.

​
Optional Variables

​
LICENSE_KEY
string
Enterprise license key for advanced features. Leave empty for open-source version.
​
NUM_WORKERS
number
default:"1"
Number of worker processes for the analyzer service.
​
SANDBOX_MODE
boolean
default:"false"
Enable sandbox mode for testing without affecting production data.
​
DISABLE_LOGGING_STATS
boolean
default:"false"
Disable anonymous usage statistics logging.

​
Database Connection

​
DB_URL
string
PostgreSQL connection string
​
REDIS_URL
string
Redis connection string
The default Redis password in the docker-compose.yaml should be changed for production deployments. Update both the cache service configuration and the REDIS_URL environment variable.

​
Docker Compose Configuration

The deployment uses the official Metlo Docker images:
  • metlo/backend:latest - Backend and Ingestor services
  • metlo/frontend:latest - Frontend web UI
  • metlo/jobrunner:latest - Background jobs and analyzer
You can pin to a specific version by setting the DOCKER_IMAGE_TAG environment variable: 
export DOCKER_IMAGE_TAG=v1.2.3

​
Management Commands

The metlo-deploy script provides several commands: 
metlo-deploy start

​
Custom Configuration

For advanced users who want to customize the deployment:
1

Download configuration files

mkdir metlo-deployment && cd metlo-deployment
wget https://raw.githubusercontent.com/metlo-labs/metlo/master/docker-compose.yaml
wget https://raw.githubusercontent.com/metlo-labs/metlo/master/init.sql
wget https://raw.githubusercontent.com/metlo-labs/metlo/master/metlo-config.yaml
2

Create environment file

Create a .env file with your configuration:
ENCRYPTION_KEY="your-base64-encoded-key"
BACKEND_URL="http://your-server-ip:8081"
EXPRESS_SECRET="your-secret-key"
LICENSE_KEY="your-license-key" # Optional
NUM_WORKERS=1
SANDBOX_MODE=false
DISABLE_LOGGING_STATS=false
3

Modify docker-compose.yaml

Customize ports, resource limits, or other settings as needed.
4

Launch services

docker-compose up -d

​
Ports

Ensure these ports are available on your host machine:
  • 8000 - Frontend web interface
  • 8080 - Backend API
  • 8081 - Ingestor/Collector API

​
Data Persistence

The deployment creates two Docker volumes for data persistence:
  • db - PostgreSQL data directory
  • cache - Redis data directory
To backup your data, use Docker volume backup strategies or connect to the database directly: 
docker exec -it metlo-db pg_dump -U postgres metlo_api_security > backup.sql

​
Troubleshooting

Check Docker logs for individual services:
docker-compose logs backend
docker-compose logs ingestor
docker-compose logs frontend
  • Verify the frontend container is running: docker ps | grep metlo-frontend
  • Check firewall rules allow port 8000
  • Ensure BACKEND_URL is correctly set and accessible from your browser
  • Verify PostgreSQL is running: docker ps | grep postgres
  • Check database logs: docker-compose logs db
  • Ensure the database initialized properly with the init.sql script
To completely reset your deployment:
metlo-deploy stop
docker-compose down -v
rm -rf /opt/metlo/.env
metlo-deploy init

​
Next Steps

Connect Data Sources

Configure connections to capture API traffic

Configure Security Rules

Set up detection rules and alerts

Build docs developers (and LLMs) love

Get started for freeTalk to us