Skip to main content

​
Overview

This guide walks you through a complete LogFleet deployment:
  1. Cloud Platform - API server and database
  2. Edge Agent - Log collection at edge locations
  3. Dashboard - Visualizing logs and metrics
By the end, you’ll have logs flowing from edge → cloud → dashboard.

​
Prerequisites

  • Docker and Docker Compose installed
  • curl for API testing
  • 5 minutes of your time

​
Step 1: Start the Cloud Platform

For this guide, we’ll use the production cloud. If you need to run locally, see Self-Hosted Setup below.

​
Create Your Account

# Register your organization
curl -X POST https://api.logfleet.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "My Company",
    "email": "[email protected]",
    "password": "SecureP@ssword123!",
    "name": "Admin User"
  }'
Save the token from the response: 
export TOKEN="eyJhbGciOiJIUzI1NiIs..."

​
Create an API Key for Edge Agents

curl -X POST https://api.logfleet.io/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "edge-agents", "permissions": ["read", "write"]}'
Save the raw_key: 
export API_KEY="lf_aBcDeFgHiJkLmNoPqRsTuVwXyZ..."
The raw API key is only shown once! Save it securely.

​
Step 2: Deploy the Edge Agent

The edge agent collects logs at your edge location and connects to the cloud. 
docker run -d \
  --name logfleet-agent \
  -e API_KEY=$API_KEY \
  -e CLOUD_URL=https://api.logfleet.io \
  -e AGENT_NAME="store-001" \
  -e LOCATION_ID="nyc-01" \
  -p 9880:9880 \
  -p 514:5140/udp \
  ghcr.io/sadhiappan/logfleet-agent:latest
This exposes:
  • Port 9880: HTTP JSON log input
  • Port 514: Syslog UDP input

​
Using Docker Compose

For production deployments with local Loki storage: 
# docker-compose.yml
version: '3.8'
services:
  logfleet-agent:
    image: ghcr.io/sadhiappan/logfleet-agent:latest
    environment:
      - API_KEY=${API_KEY}
      - CLOUD_URL=https://api.logfleet.io
      - AGENT_NAME=store-001
      - LOCATION_ID=nyc-01
    ports:
      - "9880:9880"
      - "514:5140/udp"
    volumes:
      - loki-data:/loki
    restart: unless-stopped

volumes:
  loki-data:

docker-compose up -d

​
Verify Agent Registration

Check that your agent appears in the cloud: 
curl -s https://api.logfleet.io/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" | jq
Expected output: 
{
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "store-001",
      "status": "online",
      "last_heartbeat_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

​
Step 3: Send Test Logs

Send logs to your edge agent:

​
JSON Format (HTTP)

curl -X POST http://localhost:9880 \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
    "level": "info",
    "message": "Order #12345 completed",
    "service": "pos",
    "order_id": "12345",
    "amount": 24.99
  }'

​
Multiple Logs (Batch)

curl -X POST http://localhost:9880 \
  -H "Content-Type: application/json" \
  -d '[
    {"level": "info", "message": "Customer entered store", "service": "sensors"},
    {"level": "info", "message": "Order started", "service": "pos"},
    {"level": "info", "message": "Payment received", "service": "payments", "amount": 15.99},
    {"level": "info", "message": "Order completed", "service": "pos"}
  ]'

​
Syslog Format (UDP)

echo "<14>Jan 15 10:30:00 pos-terminal app: Order completed successfully" | nc -u localhost 514

​
Step 4: View Logs in Dashboard

​
Option A: Web Dashboard

  1. Go to app.logfleet.io
  2. Log in with your credentials
  3. Click on your agent (e.g., “store-001”)
  4. Click Sample Logs to fetch recent logs

​
Option B: API

Fetch logs via the API: 
# Get agent ID first
AGENT_ID=$(curl -s https://api.logfleet.io/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" | jq -r '.agents[0].id')

# Request log sample
curl -X POST "https://api.logfleet.io/api/v1/agents/$AGENT_ID/logs/sample" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "since": "1h"}'

​
Option C: Real-Time Streaming

Start a streaming session: 
# Start stream
RESPONSE=$(curl -s -X POST https://api.logfleet.io/api/v1/stream/start \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT_ID\", \"timeout_seconds\": 300}")

SESSION_ID=$(echo $RESPONSE | jq -r '.session_id')
WS_URL=$(echo $RESPONSE | jq -r '.websocket_url')

echo "Connect to: $WS_URL"
Use a WebSocket client (like wscat) to connect and receive real-time logs.

​
Step 5: Verify Everything Works

Run this checklist to confirm your setup: 
echo "=== LogFleet E2E Verification ==="

# 1. Check agent status
echo -e "\n1. Agent Status:"
curl -s https://api.logfleet.io/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" | jq '.agents[] | {name, status, last_heartbeat_at}'

# 2. Send test log
echo -e "\n2. Sending test log..."
curl -s -X POST http://localhost:9880 \
  -H "Content-Type: application/json" \
  -d '{"message": "E2E verification test", "level": "info"}'
echo "Done"

# 3. Wait and fetch
echo -e "\n3. Fetching logs..."
sleep 2
curl -s -X POST "https://api.logfleet.io/api/v1/agents/$AGENT_ID/logs/sample" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5, "since": "5m"}' | jq '.logs[:3]'

echo -e "\n=== Verification Complete ==="

​
Self-Hosted Setup

To run LogFleet entirely on your own infrastructure:

​
Clone the Repositories

# Parent directory
mkdir logfleet && cd logfleet

# Clone agent (open source)
git clone https://github.com/sadhiappan/logfleet.git agent

# Clone cloud (requires access)
git clone https://github.com/sadhiappan/logfleet-cloud.git cloud

​
Start Cloud Platform

cd cloud
docker-compose -f compose/docker-compose.core.yml up -d
This starts:
  • API Server on port 8080
  • PostgreSQL database
  • Loki for log storage

​
Start Edge Agent

cd ../agent
docker-compose -f deploy/compose/docker-compose.core.yml up -d

​
Configure Local URLs

export CLOUD_URL=http://localhost:8080
export API_KEY="your-local-api-key"

​
Troubleshooting

​
Agent Not Connecting

  1. Check API key: Ensure API_KEY is set correctly
  2. Check URL: CLOUD_URL should include protocol (https://)
  3. Check network: Agent needs outbound HTTPS access
# Test connectivity
curl -I https://api.logfleet.io/health

​
No Logs Appearing

  1. Check agent is running: docker ps | grep logfleet
  2. Check logs are being received: docker logs logfleet-agent
  3. Send a test log: curl -X POST http://localhost:9880 -d '{"test": true}'

​
WebSocket Disconnects

  • Default idle timeout is 5 minutes
  • Increase timeout_seconds when starting stream
  • Check for network interruptions

​
What’s Next?

Custom Metrics

Extract metrics from your logs

Vector Configuration

Customize log collection

Log Streaming

Real-time log access