Lesson 9: How (and Why) to Run Your Own Forta Scan Node

Up to this point, you have been working with public Forta scan nodes to develop and test your agents. Now it’s time to learn how to run your own scan node. This gives you full control over deployment, faster processing, and the ability to add your own tracking and measurement system into a monitoring tool.

In this lesson, you will discover:

• The benefits and use cases for running your own scan node

• Step-by-step instructions to deploy one using Docker

• How to connect your bots and monitor performance locally or on a server

---

Why Run Your Own Scan Node?

Working with public Forta scan nodes is fine for development. But in production, having your own node means:

1. Lower latency: your bots run faster because traffic doesn’t go through external infrastructure

2. Full control: you can apply custom configurations, add monitoring, and update software versions

3. Better debugging: access to logs, metrics, and alert telemetry directly

4. Cost predictability: no unexpected usage limits or rate restrictions

---

Requirements and Preparations

To run a scan node, you need:

• Docker and Docker Compose installed

• Access to an Ethereum node (e.g., Infura, Alchemy)

• Forta CLI installed locally

• Enough disk space (at least 200 GB) and memory (4 GB+)

---

Deploy a Forta Scan Node

1. Create a project directory:

mkdir forta-scan-node 
cd forta-scan-node

2. Create a docker-compose.yml file with:

version: '3.7'
services:
  scan-node:
    image: forta/scan-node:latest
    container_name: forta-scan-node
    environment:
      - JSON_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
      - FORTA_KEYSTORE=./keys
    ports:
      - "8920:8920"
    volumes:
      - ./data:/data
      - ./keys:/keys

3. Save your Forta keystore (keystore.json) into a local keys folder.

4. Start the node:

docker-compose up -d

5. Check logs to make sure the system initialized properly:

docker logs -f forta-scan-node

6. Test agent connection using Forta CLI:

forta scan-node run --scan-node-url http://localhost:8920
forta agent run

---

Monitoring Your Scan Node

Once running, you should monitor:

• Logs: errors or disconnects

• Performance metrics: CPU, memory, I/O

• Block processing rate: check for falls behind head

• Alerts throughput: ensure bots deliver in time

To enable performance monitoring and metrics visualization, you can integrate tools like Prometheus and Grafana.

---

Integrating Your Bots

With your custom scan node running, adjust your bot configuration:

• Edit forta.config.json:

{
  "scanNodeUrl": "http://localhost:8920",
  "jsonRpcUrl": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
}

---

Key Concepts Recap

• Running your own scan node gives you better performance, control, and monitoring capabilities

• You can configure environment, logging, updates, and network conditions as needed

• This is essential for scaling to production and building reliable bots

• Whether local or cloud-hosted, your node becomes the central component of your detection infrastructure

In the next lesson, we will explore CI/CD pipelines for Forta Agents, how to automate testing and deployment whenever you push code.

Until next meditation,
The Blockchain Security Monk