From f5a7c2bfbcda6e6f3188122fc6c8b23d93a716aa Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 19 Aug 2026 13:56:02 +0000 Subject: [PATCH 1/2] docs: point node-operator refs at base/base and document NODE_TAG pinning --- .../node-operators/performance-tuning.mdx | 2 +- .../node-operators/run-a-base-node.mdx | 38 +++++++++++++++++-- docs/base-chain/node-operators/snapshots.mdx | 9 ++++- .../node-operators/troubleshooting.mdx | 8 ++-- .../specs/upgrades/azul/node-upgrade.mdx | 19 +++++++--- 5 files changed, 59 insertions(+), 17 deletions(-) diff --git a/docs/base-chain/node-operators/performance-tuning.mdx b/docs/base-chain/node-operators/performance-tuning.mdx index d3143f2ee..9cb3ceeb7 100644 --- a/docs/base-chain/node-operators/performance-tuning.mdx +++ b/docs/base-chain/node-operators/performance-tuning.mdx @@ -40,7 +40,7 @@ Using a recent [snapshot](/base-chain/node-operators/snapshots) can significantl ## Client Software -The [Base Node](https://github.com/base/node) repository contains the current stable configurations and instructions for running different client implementations. +The [Base Node](https://github.com/base/base) repository contains the current stable configurations and instructions for running different client implementations. Reth is currently the most performant client for running Base nodes. Future optimizations will primarily focus on Reth. You can read more about the migration to Reth [here](https://blog.base.dev/scaling-base-with-reth). diff --git a/docs/base-chain/node-operators/run-a-base-node.mdx b/docs/base-chain/node-operators/run-a-base-node.mdx index 3894978a0..e4d535cfc 100644 --- a/docs/base-chain/node-operators/run-a-base-node.mdx +++ b/docs/base-chain/node-operators/run-a-base-node.mdx @@ -3,7 +3,7 @@ title: Run a Node description: A tutorial that teaches how to set up and run a Base Node. --- -This tutorial will walk you through setting up your own [Base Node](https://github.com/base/node). +This tutorial will walk you through setting up your own [Base Node](https://github.com/base/base). ## Objectives @@ -70,11 +70,14 @@ You'll need your own L1 RPC URL. This can be one that you run yourself, or via a ## Running a Node -1. Clone the [repo](https://github.com/base/node). +The public operator node is now published from the [base/base](https://github.com/base/base) repository. The root `docker-compose.yml` pulls `ghcr.io/base/node` by default; pass `--build` to compile the current source tree instead. + +1. Clone the [repo](https://github.com/base/base). 2. Ensure you have an Ethereum L1 full node RPC available (not Base), and set `BASE_NODE_L1_ETH_RPC` & `BASE_NODE_L1_BEACON` in the appropriate `.env` file (`.env.mainnet` or `.env.sepolia`). If running your own L1 node, it needs to be synced before Base will be able to fully sync. 3. Start the node: - - **Mainnet**: `docker compose up --build` - - **Testnet**: `NETWORK_ENV=.env.sepolia docker compose up --build` + - **Mainnet (pull the published image)**: `docker compose up` + - **Mainnet (compile from source)**: `docker compose up --build` + - **Testnet**: `NETWORK_ENV=.env.sepolia docker compose up` 4. Confirm you get a response from: ```bash Terminal @@ -86,6 +89,29 @@ curl -d '{"id":0,"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["late Syncing your node may take **days** and will consume a vast amount of your requests quota. Be sure to monitor usage and up your plan if needed. +### Pin a released image with `NODE_TAG` + +`docker compose up` pulls `ghcr.io/base/node:latest` by default. To run a specific release without recompiling from source, set `NODE_TAG` to a published tag: + +```bash Terminal +NODE_TAG=v1.2.6 docker compose up +``` + +Pinning a `NODE_TAG` skips the source build entirely, so the node boots as soon as the image is pulled. Omit `--build` when using `NODE_TAG`; passing `--build` forces a local compile that overrides the pinned image. + +### Compose environment variables + +The root `docker-compose.yml` exposes a few knobs so you can override defaults from your shell or a `.env` file without editing the compose file: + +| Variable | Default | Purpose | +|----------|---------|---------| +| `NODE_TAG` | `latest` | Image tag pulled from `ghcr.io/base/node`. Set to a release tag (e.g. `v1.2.6`) to pin. | +| `NETWORK_ENV` | `.env.mainnet` | Which network env file the `execution` and `node` services load. Set to `.env.sepolia` for testnet. | +| `HOST_DATA_DIR` | `./reth-data` | Host path mounted into the execution container at `/data`. Change to point at an external volume. | +| `PROFILE` | `maxperf` | Cargo build profile used when `--build` is passed. Matches the profile used for the published image. | + +Running `docker compose up --build` compiles the current `base/base` tree using the `base` target of `etc/docker/Dockerfile.rust-services` (the same target that produces the published `ghcr.io/base/node` image), so a source build and a pinned image share the same binary layout. + ### Snapshots If you’re a Base Node operator and would like to save significant time on the initial sync, you may [restore from a snapshot](/base-chain/node-operators/snapshots#restoring-from-snapshot). The snapshots are updated every week. @@ -142,6 +168,10 @@ Applications should not connect directly to `wss://mainnet.flashblocks.base.org/ The [base](https://github.com/base/base) binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. For the full message schema and payload structure, see [Flashblocks API Overview](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview). + +`docker compose up --build` in the [base/base](https://github.com/base/base) repo will also apply the Flashblocks configuration when `RETH_FB_WEBSOCKET_URL` is set. To run without a source compile, set `RETH_FB_WEBSOCKET_URL` in your `.env` file and use `NODE_TAG=vX.Y.Z docker compose up`. + + ### Verify Flashblocks Functionality Test that your node is properly serving Flashblocks by querying a pending block: diff --git a/docs/base-chain/node-operators/snapshots.mdx b/docs/base-chain/node-operators/snapshots.mdx index 56b890c89..275b5d5a0 100644 --- a/docs/base-chain/node-operators/snapshots.mdx +++ b/docs/base-chain/node-operators/snapshots.mdx @@ -21,7 +21,7 @@ Because migration can take a while, we strongly recommend starting now. For deta ## Restoring from Snapshot -These steps assume you are in the cloned `node` directory (the one containing `docker-compose.yml`). +These steps assume you are in the cloned [base/base](https://github.com/base/base) directory (the one containing `docker-compose.yml`). These steps use the `base-reth-node` CLI to download snapshots. If you don't already have it, follow the [installation instructions](https://github.com/base/base#install-binaries) to install it first. @@ -53,7 +53,7 @@ These steps use the `base-reth-node` CLI to download snapshots. If you don't alr Ensure you have enough free disk space to download the snapshot _and_ extract its contents. The extracted data will be significantly larger than the archive. - The above presets are convenient defaults that are available at [chain.base.org/snapshots](https://chain.base.org/snapshots). You may still configure custom pruning flags with the [flag](https://github.com/base/node/blob/main/.env.mainnet#L55). It is required to download the archival snapshot and then configure your custom pruning args. + The above presets are convenient defaults that are available at [chain.base.org/snapshots](https://chain.base.org/snapshots). You may still configure custom pruning flags with the [`RETH_PRUNING_ARGS` variable](https://github.com/base/base/blob/main/.env.mainnet#L34) in `.env.mainnet` (or `.env.sepolia`). It is required to download the archival snapshot and then configure your custom pruning args. ```bash # Minimal node on Base Mainnet @@ -82,6 +82,11 @@ These steps use the `base-reth-node` CLI to download snapshots. If you don't alr ```bash cd .. + + # Pull the published image + docker compose up + + # Or compile the base/base tree locally docker compose up --build ``` diff --git a/docs/base-chain/node-operators/troubleshooting.mdx b/docs/base-chain/node-operators/troubleshooting.mdx index 4508dd7af..a7c4342d3 100644 --- a/docs/base-chain/node-operators/troubleshooting.mdx +++ b/docs/base-chain/node-operators/troubleshooting.mdx @@ -4,7 +4,7 @@ sidebarTitle: Troubleshooting description: Solutions to common issues when setting up and running a Base node, covering sync problems, networking, snapshots, and performance. --- -This guide covers common issues encountered when setting up and running a Base node using the official [Base Node Docker setup](https://github.com/base/node) and provides steps to diagnose and resolve them. +This guide covers common issues encountered when setting up and running a Base node using the official [Base Node Docker setup](https://github.com/base/base) and provides steps to diagnose and resolve them. ## General Troubleshooting Steps @@ -30,7 +30,7 @@ Before diving into specific issues, here are some general steps that often help: - **Issue**: Docker command fails (`docker compose up ...`) - **Check**: Is Docker and Docker Compose installed and the Docker daemon running? - - **Check**: Are you in the correct directory (the cloned `node` directory containing `docker-compose.yml`)? + - **Check**: Are you in the correct directory (the cloned `base/base` directory containing `docker-compose.yml`)? - **Check**: Syntax errors in the command (e.g., misspelled `NETWORK_ENV`). - **Issue**: Container fails to start, logs show errors related to `.env` files or environment variables. @@ -41,7 +41,7 @@ Before diving into specific issues, here are some general steps that often help: - **Check**: Ensure you haven't manually modified the `BASE_NODE_L2_ENGINE_AUTH` variable or the JWT file path (`$BASE_NODE_L2_ENGINE_AUTH`) unless you know what you're doing. The `docker-compose` setup usually handles this automatically. - **Issue**: Permission errors related to data volumes (`./reth-data`). - - **Check**: Ensure the user running `docker compose` has write permissions to the directory where the `node` repository was cloned. Docker needs to be able to write to `./reth-data`. Sometimes running Docker commands with `sudo` can cause permission issues later; try running as a non-root user added to the `docker` group. + - **Check**: Ensure the user running `docker compose` has write permissions to the directory where the `base/base` repository was cloned (or the `HOST_DATA_DIR` you configured). Docker needs to be able to write to `./reth-data`. Sometimes running Docker commands with `sudo` can cause permission issues later; try running as a non-root user added to the `docker` group. ### Syncing Problems @@ -124,4 +124,4 @@ Refer to the [Snapshots](/base-chain/node-operators/snapshots) guide for the cor If you’ve followed this guide and are still encountering issues, seek help from the community: - **Discord**: Join the [Base Discord](https://discord.gg/buildonbase) and post in the `🛠｜node-operators` channel, providing details about your setup, the issue, and relevant logs. -- **GitHub**: Check the [Base Node repository issues](https://github.com/base/node/issues) or open a new one if you suspect a bug. +- **GitHub**: Check the [base/base repository issues](https://github.com/base/base/issues) or open a new one if you suspect a bug. diff --git a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx index d7b84323d..747cb333a 100644 --- a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx +++ b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx @@ -11,16 +11,16 @@ Azul activated on mainnet on **May 28, 2026 18:00 UTC** (`1779991200`). See the Only `base-reth-node` (EL) and `base-consensus` (CL) support Azul. Nodes running `op-node`, `op-geth`, `op-reth`, `nethermind`, or `kona` must be migrated using the instructions below. -Both clients are available from the [base/node](https://github.com/base/node/releases) repository, where most configuration is preconfigured and can be overridden via environment variables. See the `.env.mainnet` and `.env.sepolia` files for the full list of configurable options. +Both clients are now published from the [base/base](https://github.com/base/base/releases) repository, which hosts the root `docker-compose.yml` and the `.env.mainnet` / `.env.sepolia` templates that operators previously pulled from `base/node`. Most configuration is preconfigured and can be overridden via environment variables — see those `.env` files for the full list of options. -If you build from the [base/base](https://github.com/base/base/releases) repository directly, you will need to update your `base-consensus` configuration to use the new `BASE_NODE_*` environment variables. For `base-reth-node`, you can continue to use all existing Reth tooling and configuration as before. +`docker compose up` pulls the published `ghcr.io/base/node` image; pass `--build` to compile the current tree, or set `NODE_TAG=vX.Y.Z` to pin a specific released image without a source build. ## Migrating Execution Layer ### Migrating from OP Reth -If you are already running OP Reth via [base/node](https://github.com/base/node), update to the latest version and your node will automatically use `base-reth-node`. Your existing `./reth-data` directory is fully compatible — no re-sync or snapshot restore is needed. +If you are already running OP Reth via the operator compose setup, update to the latest version and your node will automatically use `base-reth-node`. Your existing `./reth-data` directory is fully compatible — no re-sync or snapshot restore is needed. 1. Stop your node: @@ -28,9 +28,14 @@ If you are already running OP Reth via [base/node](https://github.com/base/node) docker compose down ``` -2. Update to the latest version of [base/node](https://github.com/base/node): +2. Switch to [base/base](https://github.com/base/base) (the operator node is no longer published from `base/node`) and update to the latest version: ```bash + # If you previously cloned base/node, clone base/base alongside it and copy over your .env file: + git clone https://github.com/base/base.git + cp ../node/.env.mainnet ./base/.env.mainnet # or .env.sepolia + + # If you already track base/base: git pull origin main ``` @@ -52,9 +57,11 @@ If you are already running OP Reth via [base/node](https://github.com/base/node) docker compose down ``` -2. Update to the latest version of [base/node](https://github.com/base/node): +2. Clone or update [base/base](https://github.com/base/base): ```bash + git clone https://github.com/base/base.git + # or, if already cloned: git pull origin main ``` @@ -90,7 +97,7 @@ Replace `op-node` with `base-consensus` by updating your environment variables. ### Environment Variable Mapping -If you use [base/node](https://github.com/base/node), most variables are already set in `.env.mainnet` and `.env.sepolia`. If you build from [base/base](https://github.com/base/base), use the table below to map your `op-node` environment variables to `base-consensus`. Most are optional. Run `base-consensus node --help` for the full list. +Most variables are already set in the [base/base](https://github.com/base/base) `.env.mainnet` and `.env.sepolia` templates. If you are migrating a custom `op-node` setup, use the table below to map your `op-node` environment variables to `base-consensus`. Most are optional. Run `base-consensus node --help` for the full list. | `op-node` | `base-consensus` | |-----------|-------------------| | `OP_NODE_NETWORK` | `BASE_NODE_NETWORK` | From 1a2890a781a06f1a0c8c3ddeb9e5f1fcd677ee0f Mon Sep 17 00:00:00 2001 From: roethke Date: Thu, 20 Aug 2026 10:16:27 -0700 Subject: [PATCH 2/2] add callout for base/node --- docs/base-chain/node-operators/run-a-base-node.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/node-operators/run-a-base-node.mdx b/docs/base-chain/node-operators/run-a-base-node.mdx index e4d535cfc..a96077b0c 100644 --- a/docs/base-chain/node-operators/run-a-base-node.mdx +++ b/docs/base-chain/node-operators/run-a-base-node.mdx @@ -70,7 +70,13 @@ You'll need your own L1 RPC URL. This can be one that you run yourself, or via a ## Running a Node -The public operator node is now published from the [base/base](https://github.com/base/base) repository. The root `docker-compose.yml` pulls `ghcr.io/base/node` by default; pass `--build` to compile the current source tree instead. + +**The node repository has moved.** If you've run a Base node before, you likely started from [base/node](https://github.com/base/node). As of **v1.3.0**, the operator node is published from the [base/base](https://github.com/base/base) repository, and all new releases ship there. + +The [base/node](https://github.com/base/node) repository is now maintained only to support older releases (before v1.3.0). If you're setting up a new node or upgrading, use [base/base](https://github.com/base/base). + + +The operator node is published from the [base/base](https://github.com/base/base) repository. The root `docker-compose.yml` pulls `ghcr.io/base/node` by default; pass `--build` to compile the current source tree instead. 1. Clone the [repo](https://github.com/base/base). 2. Ensure you have an Ethereum L1 full node RPC available (not Base), and set `BASE_NODE_L1_ETH_RPC` & `BASE_NODE_L1_BEACON` in the appropriate `.env` file (`.env.mainnet` or `.env.sepolia`). If running your own L1 node, it needs to be synced before Base will be able to fully sync.