Skip to main content

Docker Deployment

Deploy a Convex peer using Docker for simplified container-based deployment.

Overview​

Docker deployment provides:

  • Simplified installation
  • Consistent environment
  • Easy upgrades
  • Portable configuration

→ For traditional installation, see Manual Deployment

Prerequisites​

  • Docker 20.10+ installed
  • Docker Compose 2.0+ (optional, recommended)
  • 4+ GB RAM allocated to Docker
  • 100+ GB disk space

Quick Start​

Using Docker Run​

# Pull image
docker pull convex/convex:latest

# Run peer
docker run -d \
  --name convex-peer \
  -p 18888:18888 \
  -p 8080:8080 \
  -v convex-data:/app/data \
  convex/convex:latest peer start

Using Docker Compose​

Create docker-compose.yml:

version: '3.8'

services:
  peer:
    image: convex/convex:latest
    container_name: convex-peer
    ports:
      - "18888:18888"  # Peer port
      - "8080:8080"    # REST API
    volumes:
      - convex-data:/app/data                      # Etch store
      - ./keystore.pfx:/app/keys/keystore.pfx:ro   # keystore holding the peer key
    environment:
      - JAVA_OPTS=-Xmx4g
      - NETWORK=protonet
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  convex-data:

Start with:

docker-compose up -d

Configuration​

Environment Variables​

# docker-compose.yml environment section
environment:
  - JAVA_OPTS=-Xmx4g -XX:+UseG1GC
  - NETWORK=protonet
  - PEER_PORT=18888
  - REST_PORT=8080
  - LOG_LEVEL=info

Peer Configuration​

The peer is configured by convex peer start flags (see Manual Deployment), not a config file. Pass them as the container command, for example:

command: >
  peer start
  --peer-key 0x<peer-public-key>
  --etch /app/data/peer-store
  --peer-port 18888
  --api-port 8080
  --url your-peer.example.com:18888

Note: confirm the image name/tag and entrypoint for your Convex release before relying on this compose file.

Peer Keys​

Mount peer keys securely:

volumes:
  - ./peer-keys.dat:/app/keys/peer-keys.dat:ro

⚠️ Security: Set restrictive file permissions (600) on host.

Management​

Start/Stop​

# Start
docker-compose start

# Stop
docker-compose stop

# Restart
docker-compose restart

View Logs​

# Follow logs
docker-compose logs -f peer

# Last 100 lines
docker-compose logs --tail=100 peer

Check Status​

# Container status
docker-compose ps

# Health check
curl http://localhost:8080/api/v1/status

Monitoring​

Resource Usage​

# Container stats
docker stats convex-peer

# Detailed info
docker inspect convex-peer

Health Checks​

Add to docker-compose.yml:

services:
  peer:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Upgrading​

Pull New Image​

# Pull latest
docker-compose pull

# Restart with new image
docker-compose up -d

Backup Before Upgrade​

# Backup data volume
docker run --rm \
  -v convex-data:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/convex-data-$(date +%Y%m%d).tar.gz /data

Networking​

Custom Network​

networks:
  convex-net:
    driver: bridge

services:
  peer:
    networks:
      - convex-net

Expose Ports​

ports:
  - "18888:18888"   # Peer protocol
  - "8080:8080"     # REST API

Persistence​

Data Volumes​

volumes:
  convex-data:/app/data     # Peer state
  convex-logs:/app/logs     # Logs

Backup Strategy​

# Backup script
#!/bin/bash
docker-compose stop
docker run --rm \
  -v convex-data:/data \
  -v /backups:/backup \
  ubuntu tar czf /backup/backup-$(date +%Y%m%d).tar.gz /data
docker-compose start

Next Steps​

Resources​