Docker installation

eRPC provides official Docker images that can be used to quickly deploy the service. Follow these steps to get started:

Create configuration

Create your erpc.yaml configuration file. You can start with the minimal example:

logLevel: debug
projects:
 - id: main
   upstreams:
   - endpoint: alchemy://XXX_MY_ALCHEMY_API_KEY_XXX
   - endpoint: blastapi://XXX_MY_BLASTAPI_API_KEY_XXX

See the complete config example for all available options and detailed explanations.

Run eRPC container

Run the Docker container, mounting your configuration file:

docker run -v $(pwd)/erpc.yaml:/root/erpc.yaml \
  -p 4000:4000 -p 4001:4001 \
  ghcr.io/erpc/erpc:latest

Test the deployment

Send a test request to verify the setup:

curl --location 'http://localhost:4000/main/evm/1' \
--header 'Content-Type: application/json' \
--data '{
    "method": "eth_getBlockByNumber",
    "params": ["0x1203319", false],
    "id": 1,
    "jsonrpc": "2.0"
}'

Setup monitoring (optional)

For production deployments, we recommend setting up monitoring with Prometheus and Grafana. You can use our docker-compose setup:

# Clone the repo if you haven't
git clone https://github.com/erpc/erpc.git
cd erpc
 
# Start the monitoring stack
docker-compose up -d

See the monitoring guide for more details on metrics and dashboards.

Docker compose

For production deployments, you might want to use docker-compose to manage eRPC along with its monitoring stack. Here's a basic example:

version: '3.8'
services:
  erpc:
    image: ghcr.io/erpc/erpc:latest
    ports:
      - "4000:4000"
      - "4001:4001"
    volumes:
      - ./erpc.yaml:/root/erpc.yaml
    restart: unless-stopped

Installing custom NPM modules

When using TypeScript configuration with additional NPM dependencies beyond @erpc-cloud/config, you'll need to make these dependencies available inside the Docker container. There are two approaches to achieve this:

Option 1: Building a custom image

Create a custom Dockerfile that includes your dependencies:

FROM debian:12
 
COPY package.json pnpm-lock.yaml /root/
# COPY package.json package-lock.json /root/  # For npm
# COPY package.json yarn.lock /root/          # For yarn
 
RUN pnpm install
# RUN npm install   # For npm
# RUN yarn install  # For yarn
 
FROM ghcr.io/erpc/erpc:latest
 
COPY --from=0 /root/node_modules /root/node_modules

Build and run your custom image:

docker build -t erpc-custom -f Dockerfile.custom .
docker run -v $(pwd)/erpc.ts:/root/erpc.ts \
  -p 4000:4000 -p 4001:4001 \
  erpc-custom

Option 2: Mounting host dependencies

Alternatively, you can mount your local package.json and node_modules directly:

docker run \
  -v $(pwd)/package.json:/root/package.json \
  -v $(pwd)/node_modules:/root/node_modules \
  -v $(pwd)/erpc.ts:/root/erpc.ts \
  -p 4000:4000 -p 4001:4001 \
  ghcr.io/erpc/erpc:latest

For docker-compose, add the volumes to your service configuration:

version: '3.8'
services:
  erpc:
    image: ghcr.io/erpc/erpc:latest
    ports:
      - "4000:4000"
      - "4001:4001"
    volumes:
      - ./erpc.ts:/root/erpc.ts
      - ./package.json:/root/package.json
      - ./node_modules:/root/node_modules
    restart: unless-stopped

If you're only using the @erpc-cloud/config package, you don't need these additional steps. The base image already includes this package.

Matcher syntax Railway