Install / Docker

Docker Installation

Container-first deployment with pre-built images. Compose files for every operating mode.

Pull the Image

bash

# GitHub Container Registry (recommended)
docker pull ghcr.io/ferrum-edge/ferrum-edge:latest

# Specific version
docker pull ghcr.io/ferrum-edge/ferrum-edge:0.9.0

# Verify
docker run --rm ghcr.io/ferrum-edge/ferrum-edge:latest --version

Quick Start Examples

File Mode (no DB)

bash

docker run -d \
  --name ferrum-edge \
  -p 8000:8000 \
  -p 9000:9000 \
  -v $(pwd)/ferrum.yaml:/etc/ferrum/config.yaml:ro \
  -e FERRUM_MODE=file \
  -e FERRUM_CONFIG=/etc/ferrum/config.yaml \
  ghcr.io/ferrum-edge/ferrum-edge:latest

Database Mode

bash

docker run -d \
  --name ferrum-edge \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 9000:9000 \
  -e FERRUM_MODE=database \
  -e FERRUM_DATABASE_URL="postgres://ferrum:secret@postgres:5432/ferrum" \
  -e FERRUM_ADMIN_JWT_SECRET="your-secure-secret" \
  ghcr.io/ferrum-edge/ferrum-edge:latest

Docker Compose — Database Mode (PostgreSQL)

yaml — docker-compose.yml

version: "3.9"

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ferrum
      POSTGRES_USER: ferrum
      POSTGRES_PASSWORD: ferrum_secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ferrum"]
      interval: 5s
      timeout: 5s
      retries: 5

  ferrum-edge:
    image: ghcr.io/ferrum-edge/ferrum-edge:latest
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8000:8000"
      - "8443:8443"
      - "9000:9000"
    environment:
      FERRUM_MODE: database
      FERRUM_DATABASE_URL: postgres://ferrum:ferrum_secret@postgres:5432/ferrum
      FERRUM_ADMIN_JWT_SECRET: "change-this-in-production"
      FERRUM_LOG_LEVEL: info
      FERRUM_LOG_FORMAT: json
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/health"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  postgres_data:

Docker Compose — File Mode (SQLite)

yaml — docker-compose.file.yml

version: "3.9"

services:
  ferrum-edge:
    image: ghcr.io/ferrum-edge/ferrum-edge:latest
    ports:
      - "8000:8000"
      - "9000:9000"
    volumes:
      - ./ferrum.yaml:/etc/ferrum/config.yaml:ro
    environment:
      FERRUM_MODE: file
      FERRUM_CONFIG: /etc/ferrum/config.yaml
      FERRUM_LOG_LEVEL: info
    restart: unless-stopped

Docker Compose — Control Plane / Data Plane

yaml — docker-compose.cpdp.yml

version: "3.9"

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ferrum
      POSTGRES_USER: ferrum
      POSTGRES_PASSWORD: ferrum_secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ferrum"]
      interval: 5s
      timeout: 5s
      retries: 5

  control-plane:
    image: ghcr.io/ferrum-edge/ferrum-edge:latest
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "9000:9000"    # Admin HTTP
      - "50051:50051"  # CP gRPC
    environment:
      FERRUM_MODE: control_plane
      FERRUM_DATABASE_URL: postgres://ferrum:ferrum_secret@postgres:5432/ferrum
      FERRUM_ADMIN_JWT_SECRET: "change-this-in-production"
      FERRUM_CP_GRPC_PORT: "50051"
    restart: unless-stopped

  data-plane-1:
    image: ghcr.io/ferrum-edge/ferrum-edge:latest
    depends_on:
      - control-plane
    ports:
      - "8000:8000"
      - "8443:8443"
    environment:
      FERRUM_MODE: data_plane
      FERRUM_CP_ADDR: control-plane:50051
    restart: unless-stopped

  data-plane-2:
    image: ghcr.io/ferrum-edge/ferrum-edge:latest
    depends_on:
      - control-plane
    ports:
      - "8001:8000"
      - "8444:8443"
    environment:
      FERRUM_MODE: data_plane
      FERRUM_CP_ADDR: control-plane:50051
    restart: unless-stopped

volumes:
  postgres_data:

Docker Environment Variables

Variable	Description	Required
`FERRUM_MODE`	file \| database \| control_plane \| data_plane	Yes
`FERRUM_CONFIG`	Config file path (file mode)	file mode
`FERRUM_DATABASE_URL`	Database connection string	db modes
`FERRUM_ADMIN_JWT_SECRET`	JWT secret for Admin API	db/cp modes
`FERRUM_CP_ADDR`	Control Plane address (DP mode)	dp mode
`FERRUM_CP_GRPC_PORT`	gRPC listen port (CP mode)	No (def: 50051)
`FERRUM_LOG_LEVEL`	debug \| info \| warn \| error	No (def: info)
`FERRUM_LOG_FORMAT`	json \| text	No (def: json)

📤

Port reference: 8000 HTTP proxy • 8443 HTTPS proxy • 9000 Admin HTTP • 9443 Admin HTTPS • 50051 CP gRPC

Kubernetes Install → Admin API Reference