Running a Base Node with Docker: What the base/node Repository Actually Provides

What This Repository Solves and Who It Is For

The base/node repository addresses a narrow but real problem: packaging the Base L2 node components into a single Docker Compose workflow. It does not implement the node itself, and the repository is now archived: the README says to use releases from base/base for all new installations and upgrades. The README states that it contains a Docker build for running a Base node with base-reth-node and base-consensus. That means this repo is the Docker packaging around those two clients. The intended user is an operator who already runs an Ethereum L1 node or has access to a trusted L1 RPC and beacon endpoint. The README lists those as the first requirement, before any Base-specific setup. It is not for someone who wants to learn how Base works internally, nor for someone who expects a one-command installer that hides all infrastructure details. The quick start is short, but it assumes you know what an L1 beacon endpoint is and why you need one.

The Architecture: Two Clients, One Compose File

The repository's structure is visible from the README's description. There are two main components: base-reth-node for execution and base-consensus for consensus. These names follow the OP Stack convention, where the execution client handles transactions and state, and the consensus client handles the derivation of L2 blocks from L1 data. The Docker Compose file defines two services, execution and node, built from the same Dockerfile and started with execution-entrypoint and consensus-entrypoint, with the execution service mounting ${HOST_DATA_DIR:-./reth-data} at /data. What is clear is the data flow: the node reads from an L1 RPC for transaction data and from a beacon endpoint for consensus information. The node then produces L2 blocks and exposes an RPC on localhost:8545, as shown in the Flashblocks curl example. The design is intentionally minimal, with configuration passed through environment variables rather than a config file. That fits a containerized deployment but means every operator must manage the same set of env keys.

Getting It Running: Commands and Env Keys

The README gives a concrete path to a running node. First, you need an Ethereum L1 full node RPC and a beacon endpoint. Then you choose your network. Mainnet uses .env.mainnet, and testnet uses .env.sepolia. You set two required variables in the chosen env file: BASE_NODE_L1_ETH_RPC and BASE_NODE_L1_BEACON. There are two other required settings listed under Configuration: BASE_NODE_NETWORK and RETH_CHAIN. For mainnet, both are set to base; for Sepolia, both are base-sepolia. The sequencer URL is also network-specific, but the README does not say which env variable holds it, only that mainnet uses https://mainnet-sequencer.base.org and Sepolia uses https://sepolia-sequencer.base.org. To start, you run docker compose up --build for mainnet. For testnet, you prefix with NETWORK_ENV=.env.sepolia. The --build flag is notable: it forces a rebuild every time, which can be slow but ensures you pick up any changes in the Dockerfile or dependencies. The README does not mention a detached mode or a way to run without rebuilding, so the operator is expected to adapt the command.

Hardware and Storage: The Real Cost of Entry

The README is explicit about hardware, and the numbers are not trivial. Minimum requirements are a modern multicore CPU, 32GB of RAM with 64GB recommended, and an NVMe SSD. Storage is not a fixed number; the README gives a formula: twice the current chain size, plus the snapshot size, plus a 20% buffer. The formula reflects the fact that Base is an OP Stack rollup, so the node likely stores L2 state and possibly historical data. The production specification is an AWS i7i.12xlarge with RAID 0 of all local NVMe drives and ext4. The storage formula is honest but vague: the README links to external pages for current chain size and snapshot size, so you cannot plan without visiting those. This is a genuine limitation for operators who want to size their hardware offline. The 20% buffer is a recommendation, not a guarantee, and the README does not explain what happens if you run out of space.

Optional Features: Flashblocks, Follow Mode, and Pruning

The repository supports three optional features, each controlled by an environment variable. Flashblocks mode is enabled by setting RETH_FB_WEBSOCKET_URL. When set, the execution client runs in Flashblocks mode; otherwise it runs in vanilla mode. The README does not explain what Flashblocks does. It only shows how to test it: a curl POST to eth_getBlockByNumber with the pending block parameter on port 8545. Follow mode is enabled by setting BASE_NODE_SOURCE_L2_RPC. The name suggests the node follows another L2 node instead of deriving from L1, but the README gives no further detail. Pruning is set via RETH_PRUNING_ARGS, which likely passes arguments to the reth client. The README does not list valid values for any of these variables. That is a documentation gap. An operator who wants to enable pruning must guess the argument format or look at the .env files, which are not shown in the README. The same applies to Flashblocks: the websocket URL format is not specified. This is a case where the repository's value is in the compose setup, but the operational details are left to the underlying client documentation.

What the README Does Not Tell You: Limitations

Several limitations are visible from the README, even without running the node. First, the README says nothing about sync time, checkpoint sync, or how to verify the node is healthy beyond the Flashblocks curl example. There is no mention of logs, health checks, or monitoring. Second, the README states that the node software is provided "AS IS" without warranty, and that there are no guarantees about asset protection or security. That is a legal disclaimer, but it also signals that the project does not promise production readiness for all setups. Third, the storage formula assumes you have access to the external stats pages, and the README does not offer a fallback estimate. Fourth, the repository is a Docker wrapper, so it is the wrong tool if you need to run the node on a system without Docker, or if you want to integrate the node into a Kubernetes cluster with custom resource limits. The compose file might be adaptable, but that is not documented. Finally, the repository is archived: the README says development and releases have moved to base/base and that this repository is no longer maintained, so v1.2.0 (2026-07-22) is the newest release here.

Alternatives and How They Differ in Approach

The obvious alternative is to run base-reth-node and base-consensus directly, without this Docker wrapper. That approach gives you more control over process management, logging, and resource allocation, but it requires you to handle the configuration and networking yourself. The base/node repository exists to remove that overhead, so the trade-off is convenience versus flexibility. Another alternative is to use a third-party node provider that hosts Base nodes, such as Alchemy or Infura, but those are managed services and do not give you the same level of control or the ability to run your own infrastructure. The key difference is that base/node is a self-hosted, Docker-centric solution, while a managed provider is a remote API. Self-hosting means you bear the hardware and maintenance cost. The repository's value is that it standardizes the Docker build, but it does not reduce the operational burden of running a full node.

Maintenance and License Considerations

The repository is MIT licensed, which is permissive and allows commercial use, modification, and redistribution. The README includes a disclaimer that disclaims warranties, but that is separate from the license. The release history shows v1.1.0 in June 2026, v1.1.1 shortly after, and v1.2.0 in July 2026, but the repository is now archived and the README says it is no longer maintained, with development and releases moved to base/base. The Dockerfile pins the Rust toolchain (RUST_VERSION=1.93) and clones base-reth-node at the tag listed in versions.env, failing the build if the commit hash does not match. Because the repository is archived, new installations and upgrades should follow releases from base/base. The license is not a barrier.

Editorial conclusion

This repository is archived and the README directs new installations and upgrades to releases from base/base; use it only to understand the Docker Compose setup with env templates for mainnet and Sepolia. Do not adopt it if you need a standalone binary, a non-Docker deployment, or if you cannot provide a reliable L1 RPC and beacon endpoint, since those are mandatory and the README gives no fallback. Before using it, verify that your storage planning follows the 2x chain size plus snapshot plus 20% buffer formula, and test Flashblocks mode on Sepolia first if you plan to use it in production. The repository is MIT licensed but archived, and it is a wrapper: your real risk is the underlying base-reth-node and base-consensus clients, not the compose files.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes