Docker deployment

Image reference

ghcr.io/erpc/erpc:latest          # latest stable
ghcr.io/erpc/erpc:<version>       # e.g. ghcr.io/erpc/erpc:0.0.46

Pin to a specific version tag in production. The latest tag is overwritten on every release. Both linux/amd64 and linux/arm64 are published in the same multi-arch manifest.

Port mapping

Expose only the ports your deployment actually uses. 4001 metrics should be reachable by your Prometheus scraper but not exposed publicly.

Volume mounts

Default auto-discovery in the container checks /erpc.yaml then /erpc.ts. To use a different path, pass --config /path/to/config.yaml as the CMD override.

Environment variables

See CLI & env vars for the full reference including POD_NAME, AWS credentials, and OTEL variables.

Production docker-compose with monitoring

version: '3.8'
services:
  erpc:
    image: ghcr.io/erpc/erpc:latest
    ports:
      - "4000:4000"
      - "4001:4001"
    volumes:
      - ./erpc.yaml:/erpc.yaml
    environment:
      LOG_LEVEL: info
      GOGC: "30"
      GOMEMLIMIT: 2GiB
      INSTANCE_ID: erpc-prod-01
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:4000/healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 15s
 
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
 
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Healthcheck integration

eRPC exposes GET /healthcheck on port 4000. It returns 200 OK once the proxy is listening and at least one upstream is reachable.

# Manual check
curl -fsS http://localhost:4000/healthcheck

For Docker healthcheck:

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:4000/healthcheck"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 15s

Kubernetes liveness/readiness probes use the same endpoint:

livenessProbe:
  httpGet:
    path: /healthcheck
    port: 4000
  initialDelaySeconds: 15
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthcheck
    port: 4000
  initialDelaySeconds: 5
  periodSeconds: 5

Production memory tuning

The Go runtime defaults work for most workloads. Tune GOGC and GOMEMLIMIT together:

# Tight memory ceiling (2 GiB container limit)
docker run \
  -e GOGC=30 \
  -e GOMEMLIMIT=1600MiB \
  -v $(pwd)/erpc.yaml:/erpc.yaml \
  -p 4000:4000 -p 4001:4001 \
  --memory=2g \
  ghcr.io/erpc/erpc:latest

Rule of thumb: set GOMEMLIMIT to ~80% of --memory so the GC triggers before the OOM-killer. Lower GOGC (25-50) keeps heaps smaller at the cost of slightly higher CPU. See CLI & env vars — GOGC and GOMEMLIMIT for details.

Restart policy

Always set restart: unless-stopped (compose) or --restart=unless-stopped (docker run) in production. eRPC exits with a non-zero code on config errors or failed upstream initialization — the restart policy will handle transient failures (e.g. a dependent service not yet up).

For always vs unless-stopped: use unless-stopped so a deliberate docker stop doesn't trigger an immediate restart.

Common pitfalls

• Config volume not mounted — without -v ./erpc.yaml:/erpc.yaml, auto-discovery finds nothing in / and the process exits. Pass --config explicitly or ensure the mount path matches.
• Port 4000 already in use — eRPC fails to bind and exits with code 2. Check with lsof -i :4000 and pick a free host port via -p 4100:4000.
• Image cache — docker pull ghcr.io/erpc/erpc:latest may serve a cached layer. Force a fresh pull with docker pull --no-cache or pin to a version digest.
• GOMEMLIMIT without GOGC — the runtime relies entirely on the soft limit, which can cause large heap swings just under the limit. Always pair them.
• TypeScript config auto-discovery — the container's cwd is /. Drop your erpc.ts at /erpc.ts or pass --config /path/to/erpc.ts as the CMD.
• gRPC port not exposed — port 4100 is only active when server.grpc is configured. Exposing it on an image without gRPC config is harmless but confusing.