Docker Container Deployment

Deploy PiVirt components (pivirtd, agent, director) as containerized workloads using Docker and Docker Compose for local development or testing.

Prerequisites

• Docker 24.0+
• Docker Compose 2.20+
• KVM support on host

Quick Start

Single Node with Docker Compose

# Create directory
mkdir pivirt-docker && cd pivirt-docker

# Download compose file
curl -O https://raw.githubusercontent.com/pilab-dev/pivirt/main/docker/docker-compose.yaml

# Start PiVirt
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

docker-compose.yaml

version: '3.8'

services:
  pivirtd:
    image: pilab-cloud/pivirtd:latest
    container_name: pivirtd
    privileged: true
    ports:
      - "9001:9001"
      - "9002:9002"
    volumes:
      - /dev/kvm:/dev/kvm
      - pivirtd-data:/var/lib/pivirtd
      - ./config/pivirtd:/etc/pivirtd
    environment:
      - PIVIRT_LOG_LEVEL=info
    restart: unless-stopped

  agent:
    image: pilab-cloud/pivirt-agent:latest
    container_name: pivirt-agent
    ports:
      - "8443:8443"
      - "8444:8444"
    volumes:
      - ./config/agent:/etc/pivirt-agent
    environment:
      - PIVIRT_LOG_LEVEL=info
    depends_on:
      - pivirtd
    restart: unless-stopped

  iscsiman:
    image: pilab-cloud/iscsiman:latest
    container_name: iscsiman
    privileged: true
    ports:
      - "9003:9003"
    volumes:
      - /dev:/dev
      - ./config/iscsiman:/etc/iscsiman
    environment:
      - PIVIRT_LOG_LEVEL=info
    restart: unless-stopped

volumes:
  pivirtd-data:

Configuration

Create Configuration Files

# Create config directories
mkdir -p config/{pivirtd,agent,iscsiman}

# Create pivirtd config
cat > config/pivirtd/config.yaml <<EOF
server:
  grpc_addr: "0.0.0.0:9001"
  http_addr: "0.0.0.0:9002"

hypervisor:
  type: "qemu"

storage:
  default_pool: "default"
  pools:
    - name: "default"
      type: "dir"
      path: "/var/lib/pivirtd/images"

network:
  default_bridge: "virbr0"

logging:
  level: "info"
  format: "json"
EOF

# Create agent config
cat > config/agent/config.yaml <<EOF
server:
  connectrpc:
    addr: "0.0.0.0:8443"
  grpc_internal:
    addr: "0.0.0.0:9000"
  metrics:
    addr: "0.0.0.0:8444"

backends:
  pivirtd:
    endpoint: "pivirtd:9001"
    timeout: "30s"

logging:
  level: "info"
  format: "json"
EOF

Running Individual Components

pivirtd

docker run -d \
  --name pivirtd \
  --privileged \
  -p 9001:9001 \
  -p 9002:9002 \
  -v /dev/kvm:/dev/kvm \
  -v pivirtd-data:/var/lib/pivirtd \
  -v ./config/pivirtd:/etc/pivirtd \
  pilab-cloud/pivirtd:latest

agent

docker run -d \
  --name pivirt-agent \
  -p 8443:8443 \
  -p 8444:8444 \
  -v ./config/agent:/etc/pivirt-agent \
  --link pivirtd \
  pilab-cloud/pivirt-agent:latest

pvcli

docker run --rm -it \
  -v ~/.config/pvcli:/root/.config/pvcli \
  pilab-cloud/pvcli:latest \
  vm list

Multi-Node Setup

Node 1 (Control Plane)

docker-compose.node1.yaml

version: '3.8'

services:
  pivirtd:
    image: pilab-cloud/pivirtd:latest
    privileged: true
    ports:
      - "9001:9001"
      - "9002:9002"
    volumes:
      - /dev/kvm:/dev/kvm
      - pivirtd-data:/var/lib/pivirtd
      - ./config/pivirtd:/etc/pivirtd

  agent:
    image: pilab-cloud/pivirt-agent:latest
    ports:
      - "8443:8443"
    volumes:
      - ./config/agent:/etc/pivirt-agent
    depends_on:
      - pivirtd

  etcd:
    image: quay.io/coreos/etcd:v3.5.0
    ports:
      - "2379:2379"
    environment:
      - ETCD_NAME=node1
      - ETCD_DATA_DIR=/etcd
      - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
      - ETCD_ADVERTISE_CLIENT_URLS=http://node1:2379
    volumes:
      - etcd-data:/etcd

volumes:
  pivirtd-data:
  etcd-data:

Node 2 (Worker)

docker-compose.node2.yaml

version: '3.8'

services:
  pivirtd:
    image: pilab-cloud/pivirtd:latest
    privileged: true
    ports:
      - "9001:9001"
    volumes:
      - /dev/kvm:/dev/kvm
      - pivirtd-data:/var/lib/pivirtd
      - ./config/pivirtd:/etc/pivirtd

  agent:
    image: pilab-cloud/pivirt-agent:latest
    ports:
      - "8443:8443"
    volumes:
      - ./config/agent:/etc/pivirt-agent
    environment:
      - ETCD_ENDPOINTS=http://node1:2379
    depends_on:
      - pivirtd

volumes:
  pivirtd-data:

Networking

Host Networking

services:
  pivirtd:
    network_mode: "host"

Custom Network

networks:
  pivirt-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

services:
  pivirtd:
    networks:
      - pivirt-net

Storage

Bind Mounts

volumes:
  - /var/lib/pivirtd:/var/lib/pivirtd

Named Volumes

volumes:
  - pivirtd-data:/var/lib/pivirtd

volumes:
  pivirtd-data:
    driver: local

NFS Storage

volumes:
  - type: volume
    source: nfs-storage
    target: /var/lib/pivirtd
    volume:
      driver: local
      driver_opts:
        type: nfs
        o: addr=10.0.1.100,rw
        device: ":/exports/pivirtd"

Monitoring

Prometheus Metrics

# Access metrics
curl http://localhost:9002/metrics  # pivirtd
curl http://localhost:8444/metrics  # agent

Prometheus Configuration

prometheus.yml

scrape_configs:
  - job_name: 'pivirt-docker'
    static_configs:
      - targets:
        - 'localhost:9002'
        - 'localhost:8444'

Troubleshooting

Check Container Logs

# View all logs
docker compose logs -f

# View specific service
docker compose logs pivirtd -f

# View last 100 lines
docker compose logs --tail=100 pivirtd

Check Container Status

# List containers
docker compose ps

# Inspect container
docker inspect pivirtd

# Check health
docker compose exec pivirtd curl http://localhost:9002/health

KVM Access Issues

# Check KVM device
ls -la /dev/kvm

# Add user to kvm group
sudo usermod -aG kvm $USER

# Restart Docker
sudo systemctl restart docker

Related

• Getting Started
• Bare Metal Installation
• Kubernetes Installation