Docker Installation

Deploy Telegen using Docker or Docker Compose.

Prerequisites

Docker 20.10+
Linux host with kernel 4.18+ (for eBPF)
Root/sudo access

Quick Start

Single Container (Agent Mode)

docker run -d --name telegen \
  --privileged \
  --pid=host \
  --network=host \
  -v /sys:/sys:ro \
  -v /proc:/host/proc:ro \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -e TELEGEN_OTLP_ENDPOINT=otel-collector:4317 \
  ghcr.io/mirastacklabs-ai/telegen:latest

With Configuration File

# Create config directory
mkdir -p /etc/telegen

# Create configuration
cat > /etc/telegen/config.yaml <<EOF
telegen:
  mode: agent
  service_name: telegen
  log_level: info

otlp:
  endpoint: "otel-collector:4317"
  protocol: grpc
  insecure: true

agent:
  ebpf:
    enabled: true
    network: true
    syscalls: true
  profiling:
    enabled: true
    cpu: true
    memory: true
  discovery:
    enabled: true
EOF

# Run with config
docker run -d --name telegen \
  --privileged \
  --pid=host \
  --network=host \
  -v /sys:/sys:ro \
  -v /proc:/host/proc:ro \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc/telegen:/etc/telegen:ro \
  ghcr.io/mirastacklabs-ai/telegen:latest \
  --config=/etc/telegen/config.yaml

Docker Compose

Agent Mode

Create docker-compose.yaml:

version: '3.8'

services:
  telegen:
    image: ghcr.io/mirastacklabs-ai/telegen:latest
    container_name: telegen
    restart: unless-stopped
    privileged: true
    pid: host
    network_mode: host
    
    environment:
      - TELEGEN_OTLP_ENDPOINT=otel-collector:4317
      - TELEGEN_LOG_LEVEL=info
    
    volumes:
      - /sys:/sys:ro
      - /proc:/host/proc:ro
      - /sys/kernel/debug:/sys/kernel/debug
      - /sys/fs/bpf:/sys/fs/bpf
      - ./config.yaml:/etc/telegen/config.yaml:ro
    
    command: ["--config=/etc/telegen/config.yaml", "--mode=agent"]
    
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Collector Mode

version: '3.8'

services:
  telegen-collector:
    image: ghcr.io/mirastacklabs-ai/telegen:latest
    container_name: telegen-collector
    restart: unless-stopped
    
    ports:
      - "162:162/udp"   # SNMP traps
      - "19090:19090"   # Metrics
      - "8080:8080"     # Health
    
    environment:
      - TELEGEN_OTLP_ENDPOINT=otel-collector:4317
      - DELL_PASSWORD=${DELL_PASSWORD}
      - PURE_TOKEN=${PURE_TOKEN}
      - SNMP_AUTH_PASSWORD=${SNMP_AUTH_PASSWORD}
    
    volumes:
      - ./collector-config.yaml:/etc/telegen/config.yaml:ro
    
    command: ["--config=/etc/telegen/config.yaml", "--mode=collector"]
    
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

Full Stack (Agent + Collector + OTel Collector)

version: '3.8'

services:
  # OpenTelemetry Collector
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    container_name: otel-collector
    restart: unless-stopped
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "8888:8888"   # Metrics
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
    command: ["--config=/etc/otelcol/config.yaml"]
  
  # Telegen Agent
  telegen-agent:
    image: ghcr.io/mirastacklabs-ai/telegen:latest
    container_name: telegen-agent
    restart: unless-stopped
    privileged: true
    pid: host
    network_mode: host
    depends_on:
      - otel-collector
    
    environment:
      - TELEGEN_OTLP_ENDPOINT=localhost:4317
    
    volumes:
      - /sys:/sys:ro
      - /proc:/host/proc:ro
      - /sys/kernel/debug:/sys/kernel/debug
      - /sys/fs/bpf:/sys/fs/bpf
      - ./agent-config.yaml:/etc/telegen/config.yaml:ro
    
    command: ["--config=/etc/telegen/config.yaml", "--mode=agent"]
  
  # Telegen Collector (optional)
  telegen-collector:
    image: ghcr.io/mirastacklabs-ai/telegen:latest
    container_name: telegen-collector
    restart: unless-stopped
    depends_on:
      - otel-collector
    
    ports:
      - "162:162/udp"
    
    environment:
      - TELEGEN_OTLP_ENDPOINT=otel-collector:4317
    
    volumes:
      - ./collector-config.yaml:/etc/telegen/config.yaml:ro
    
    command: ["--config=/etc/telegen/config.yaml", "--mode=collector"]

Configuration Files

Agent Configuration (agent-config.yaml)

telegen:
  mode: agent
  service_name: telegen
  log_level: info

otlp:
  endpoint: "localhost:4317"
  protocol: grpc
  insecure: true

agent:
  ebpf:
    enabled: true
    network:
      enabled: true
      http: true
      grpc: true
      dns: true
    syscalls:
      enabled: true
  
  profiling:
    enabled: true
    sample_rate: 99
    cpu: true
    off_cpu: true
    memory: true
  
  discovery:
    enabled: true
    interval: 30s
  
  security:
    enabled: true
    syscall_audit: true
    file_integrity: true

Collector Configuration (collector-config.yaml)

telegen:
  mode: collector
  service_name: telegen-collector
  log_level: info

otlp:
  endpoint: "otel-collector:4317"
  protocol: grpc
  insecure: true

collector:
  snmp:
    enabled: true
    poll_interval: 60s
    
    targets:
      - name: "core-switch"
        address: "10.0.1.1:161"
        version: "v3"
        security:
          user: "monitor"
          auth_protocol: "SHA256"
          auth_password: "${SNMP_AUTH_PASSWORD}"
          priv_protocol: "AES256"
          priv_password: "${SNMP_PRIV_PASSWORD}"
        modules:
          - if_mib
          - entity_mib
    
    trap_receiver:
      enabled: true
      listen_address: ":162"
  
  storage:
    dell:
      enabled: true
      targets:
        - name: "powerstore-01"
          address: "https://10.0.10.100"
          username: "monitor"
          password: "${DELL_PASSWORD}"

OTel Collector Configuration (otel-config.yaml)

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 10s
    send_batch_size: 1000

exporters:
  debug:
    verbosity: detailed
  
  # Add your backend exporters here
  # otlp/jaeger:
  #   endpoint: jaeger:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Environment Variables

Variable	Description	Default
`TELEGEN_OTLP_ENDPOINT`	OTLP endpoint	`localhost:4317`
`TELEGEN_OTLP_PROTOCOL`	Protocol (grpc/http)	`grpc`
`TELEGEN_LOG_LEVEL`	Log level	`info`
`TELEGEN_MODE`	agent or collector	`agent`
`TELEGEN_SERVICE_NAME`	Service name	`telegen`

Volume Mounts

Required for Agent Mode

Host Path	Container Path	Mode	Purpose
`/sys`	`/sys`	ro	Kernel info
`/proc`	`/host/proc`	ro	Process info
`/sys/kernel/debug`	`/sys/kernel/debug`	rw	eBPF debugfs
`/sys/fs/bpf`	`/sys/fs/bpf`	rw	BPF filesystem

Optional

Host Path	Container Path	Purpose
`/var/log`	`/var/log`	Log collection
`/var/run/docker.sock`	`/var/run/docker.sock`	Container discovery

Commands

Start

docker compose up -d

Stop

docker compose down

View Logs

docker compose logs -f telegen

Check Status

docker compose ps

Check Health

curl http://localhost:8080/healthz

View Metrics

curl http://localhost:19090/metrics

Troubleshooting

Container Won’t Start

# Check logs
docker logs telegen

# Verify privileged mode
docker inspect telegen | grep -i privileged

eBPF Errors

# Check kernel version
uname -r

# Check BPF filesystem
mount | grep bpf

# Check BTF availability
ls /sys/kernel/btf/vmlinux

No Telemetry

# Test OTLP connectivity
docker exec telegen wget -q -O- http://otel-collector:4317/health

# Check agent health
docker exec telegen wget -q -O- http://localhost:8080/healthz

Next Steps

Linux Installation - systemd installation
Configuration - Configuration reference