Skip to main content

​
Get Started with Metlo

This guide will help you deploy Metlo locally using Docker Compose and start monitoring your APIs in under 5 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Docker (version 20.10 or later)
  • Docker Compose (version 2.0 or later)
  • At least 2GB of available RAM
  • Port availability: 8000 (frontend), 8080 (backend), 8081 (ingestor)

​
Installation

1

Clone the Repository

First, clone the Metlo repository:
git clone https://github.com/metlo-labs/metlo.git
cd metlo
2

Set Environment Variables

Create a .env file in the root directory with required configuration:
# Generate a random encryption key
ENCRYPTION_KEY=$(openssl rand -base64 32)

# Generate a random session secret
EXPRESS_SECRET=$(openssl rand -base64 32)

# Backend URL (for local development)
BACKEND_URL=http://localhost:8080
On Linux/Mac, you can generate secure random keys using openssl rand -base64 32
3

Start Metlo Services

Launch all Metlo components using Docker Compose:
docker-compose up -d
This will start:
  • PostgreSQL database
  • Redis cache
  • Metlo backend (port 8080)
  • Metlo frontend (port 8000)
  • Metlo ingestor (port 8081)
  • Metlo analyzer
  • Metlo jobs runner
The first startup may take 2-3 minutes as Docker pulls the necessary images and initializes the database.
4

Access the Dashboard

Once all services are running, open your browser and navigate to:
http://localhost:8000
You should see the Metlo dashboard interface.

​
Verify Installation

Check that all services are running correctly: 
docker-compose ps
You should see all services in the “Up” state: 
NAME                  STATUS
metlo-frontend        Up
metlo-backend         Up
metlo-ingestor        Up
metlo-analyzer        Up
metlo-jobs            Up
metlo-db              Up
metlo-cache           Up

​
Configure Traffic Monitoring

To start monitoring your APIs, you need to install a Metlo ingestor in your application.

​
Node.js Applications

For Node.js apps (Express, Koa, Fastify), install the Metlo package:
1

Install Package

npm install metlo
# or
yarn add metlo
2

Configure Express Middleware

Add Metlo to your Express application:
const metlo = require("metlo");
const express = require("express");

// Initialize Metlo - must be first
metlo("<YOUR_METLO_API_KEY>", "http://localhost:8081");

const app = express();

// Your routes here
app.get("/api/users", (req, res) => {
  res.json({ users: [] });
});

app.listen(3000);
Replace <YOUR_METLO_API_KEY> with an actual API key from your Metlo dashboard.
3

Start Your Application

Start your application and make some API requests. Traffic will automatically appear in the Metlo dashboard.

​
Python Applications

For Python apps (Flask, Django, FastAPI), use the Python ingestor: 
from flask import Flask
from metlo.flask import MetloFlask

app = Flask(__name__)

# Initialize Metlo
MetloFlask(app, "http://localhost:8081", "<YOUR_METLO_API_KEY>")

@app.route("/api/users")
def get_users():
    return {"users": []}

​
Other Languages

Metlo supports multiple languages:
  • Go: Import the Go ingestor package
  • Java: Add the Java agent dependency
  • Kubernetes: Deploy the DAPR integration
Refer to the specific ingestor documentation for detailed setup instructions.

​
Configuration Options

​
Environment Variables

The docker-compose.yaml supports these key environment variables:
VariableDescriptionRequired
ENCRYPTION_KEYKey for encrypting sensitive dataYes
EXPRESS_SECRETSession secret for backendYes
BACKEND_URLBackend API URLYes
LICENSE_KEYEnterprise license keyNo
NUM_WORKERSNumber of analyzer workersNo
DISABLE_LOGGING_STATSDisable usage statisticsNo

​
Custom Configuration

You can customize Metlo behavior using metlo-config.yaml: 
# metlo-config.yaml
globalFullTraceCapture:
  enabled: true
  
apiEndpoints:
  - path: /api/v1/users
    method: GET
    sensitiveData:
      - email
      - phone

​
What’s Next?

Architecture Overview

Learn how Metlo components work together

Deploy to Production

Deploy Metlo to AWS, GCP, or Azure

Security Testing

Create security tests for your APIs

Attack Detection

Configure attack detection rules

​
Troubleshooting

If services fail to start, ensure ports 8000, 8080, and 8081 are not already in use.

​
Common Issues

Services won’t start 
# Check for port conflicts
netstat -tuln | grep -E '8000|8080|8081'

# View service logs
docker-compose logs backend
docker-compose logs ingestor
Database connection errors 
# Restart the database and wait for initialization
docker-compose restart db
docker-compose logs -f db
No traffic appearing in dashboard
  • Verify the ingestor is reachable at http://localhost:8081
  • Check that the Metlo middleware is initialized before your routes
  • Ensure your application is making requests to monitored endpoints

​
Stop Metlo

To stop all Metlo services: 
# Stop services but keep data
docker-compose stop

# Stop services and remove containers (keeps volumes)
docker-compose down

# Remove everything including data volumes
docker-compose down -v

Build docs developers (and LLMs) love

Get started for freeTalk to us