hemilabs · joshuasing · Oct 20, 2025
@@ -0,0 +1,7 @@
+# Hemi Node Documentation
+
+- [Quick Start](quick-start.md)
+- [Setup guide](setup.md)
+- [Profiles](profiles.md)
+<!-- TODO: add configuration option docs -->
+<!-- TODO: add updating nodes docs -->
@@ -0,0 +1,154 @@
+# Hemi Node Profiles
+
+The Docker compose files support running multiple different profiles, depending on your use case and requirements.
+
+> [!TIP]
+> For most use cases, the [`hemi-min` profile](#profile-hemi-min) is recommended.
+
+Each profile runs a different set of components, and has a different use case.
+
+- [**`full` profile** - Runs every required component](#profile-full)
+  - Includes all Hemi L2 components
+  - Includes BFG (used for PoP Mining) and the required `electrs` indexer
+  - Includes Ethereum L1 nodes
+  - Includes Bitcoind node (used by `electrs`)
+
+- [**`hemi` profile** - Runs the Hemi components, using external RPC endpoints](#profile-hemi)
+  - Includes all Hemi L2 components
+  - Includes BFG (used for PoP mining) and the required `electrs` indexer
+  - External RPC endpoints are required for:
+    - Ethereum L1 nodes (geth and prysm)
+    - Bitcoind (used by BFG through `electrs`)
+
+- [**`hemi-min` profile - Lightweight profile**](#profile-hemi-min)
+  - Includes all Hemi L2 components
+  - Does not include BFG (and its required `electrs` indexer)
+  - External RPC endpoints are required for:
+    - Ethereum L1 nodes (geth and prysm)
+
+- [**`l1` profile - Ethereum and Bitcoin L1 components only**](#profile-l1)
+  - Ethereum L1 nodes (geth and prysm)
+  - Bitcoind node
+
+| Profile            | `full` | `hemi`       | `hemi-min`   | `l1` |
+|--------------------|--------|--------------|--------------|------|
+| Hemi `op-geth`     | ✅      | ✅            | ✅            |      |
+| Hemi `op-node`     | ✅      | ✅            | ✅            |      |
+| Hemi `bssd`        | ✅      | ✅            | ✅            |      |
+| Hemi `bfgd`        | ✅      | ✅            |              |      |
+| Ethereum `prysm`   | ✅      | RPC required | RPC required | ✅    |
+| Ethereum `geth`    | ✅      | RPC required | RPC required | ✅    |
+| Bitcoin `bitcoind` | ✅      | RPC required |              | ✅    |
+| Bitcoin `electrs`  | ✅      | ✅            |              |      |
+
+> [!IMPORTANT]
+> Each profile has entirely different system requirements. Please
+> see [System Requirements](setup.md#system-requirements) for up-to-date requirements for each profile.
+
+## Profile `full`
+
+Runs a Hemi L2 node (`op-geth` and `op-node`), Hemi Bitcoin Finality Governor (used by PoP Miners) and Ethereum L1
+components.
+
+> [!WARNING]
+> This profile runs Ethereum L1 components, in addition to the Hemi L2 components. This profile requires significantly
+> more disk capacity in order to store L1 data.
+>
+> In most cases, it is preferable to use the `hemi` or `hemi-min` profile and provide RPC endpoints for external
+> Ethereum L1 nodes.
+
+**Services**
+
+| Service         | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `bfgd`          | Hemi Bitcoin Finality Governor (used by PoP Miners) |
+| `bfgd-postgres` | PostgreSQL database for `bfgd`                      |
+| `bitcoind`      | Bitcoin full node (used by `electrs`)               |
+| `electrs`       | Bitcoin indexer (used by `bfgd`)                    |
+| `bssd`          | Hemi Bitcoin Secure Sequencer                       |
+| `op-geth-l2`    | Hemi L2 op-geth node                                |
+| `op-node`       | Hemi L2 op-node                                     |
+| `geth-l1`       | Ethereum L1 geth node                               |
+| `prysm`         | Prysm (L1)                                          |
+
+**Init containers**
+
+| Service               | Description                                                   |
+|-----------------------|---------------------------------------------------------------|
+| `op-geth-l2-init`     | Fixes directory ownership for `op-geth-l2` data directory     |
+| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory |
+
+## Profile `hemi`
+
+Runs a Hemi L2 node (`op-geth` and `op-node`) and a Hemi Bitcoin Finality Governor (used by PoP Miners).
+
+> [!TIP]
+> This profile runs the services necessary for use with a `popmd` (PoP Miner) daemon:
+>   - Bitcoin Finality Governor (RPC used by `popmd`)
+>   - Electrs (used by `bfgd`)
+
+**Requires**
+
+- Ethereum L1 RPC URL (must be set as `GETHL1ENDPOINT` environment variable)
+- Ethereum Prysm RPC URL (must be set as `PRYSMENDPOINT` environment variable)
+- Bitcoind RPC URL (must be set as `BITCOINENDPOINT` environment variable)
+
+**Services**
+
+| Service         | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `bfgd`          | Hemi Bitcoin Finality Governor (used by PoP Miners) |
+| `bfgd-postgres` | PostgreSQL database for `bfgd`                      |
+| `electrs`       | Bitcoin indexer (used by `bfgd`)                    |
+| `bssd`          | Hemi Bitcoin Secure Sequencer                       |
+| `op-geth-l2`    | Hemi L2 op-geth node                                |
+| `op-node`       | Hemi L2 op-node                                     |
+
+**Init containers**
+
+| Service               | Description                                                   |
+|-----------------------|---------------------------------------------------------------|
+| `op-geth-l2-init`     | Fixes directory ownership for `op-geth-l2` data directory     |
+| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory |
+
+## Profile `hemi-min`
+
+Runs a Hemi L2 node (`op-geth` and `op-node`).
+
+> [!TIP]
+> This profile is recommended for most use cases, and is the most lightweight profile.
+>
+> This profile does not run the components necessary to run `popmd` (PoP Miner). See the [`hemi` profile](#profile-hemi)
+> if you require the Bitcoin Finality Governor to run a PoP Miner.
+
+**Requires**
+
+- Ethereum L1 RPC URL (must be set as `GETHL1ENDPOINT` environment variable)
+- Ethereum Prysm RPC URL (must be set as `PRYSMENDPOINT` environment variable)
+
+**Services**
+
+| Service      | Description                   |
+|--------------|-------------------------------|
+| `bssd`       | Hemi Bitcoin Secure Sequencer |
+| `op-geth-l2` | Hemi L2 op-geth node          |
+| `op-node`    | Hemi L2 op-node               |
+
+**Init containers**
+
+| Service               | Description                                                   |
+|-----------------------|---------------------------------------------------------------|
+| `op-geth-l2-init`     | Fixes directory ownership for `op-geth-l2` data directory     |
+| `op-geth-l2-init-tbc` | Fixes directory ownership for `op-geth-l2` TBC data directory |
+
+## Profile `l1`
+
+Runs only Ethereum L1 and Bitcoin components. **This does not run any Hemi services.**
+
+**Services**
+
+| Service    | Description           |
+|------------|-----------------------|
+| `bitcoind` | Bitcoin full node     |
+| `geth-l1`  | Ethereum L1 geth node |
+| `prysm`    | Prysm (L1)            |
@@ -0,0 +1,158 @@
+# Hemi Node Quick Start
+
+This document is a quick-start guide to set up and run the Hemi stack with P2P nodesÒ and RPC access. *This does not set
+up a batcher or sequencer.*
+
+> [!NOTE]
+> This guide is only for users looking to run a node on the Hemi Network, and is not required to use a wallet (e.g.
+> Rabby, Metamask, etc.) to interact with the Hemi Network, or run a PoP Miner.
+
+> [!IMPORTANT]
+> **This is the quick-start guide, and glosses over the details of running a node.**
+> For more information, please see our [full setup guide](setup.md).
+
+**Table of Contents**
+
+* [Prerequisites](#prerequisites)
+  * [System Requirements](#system-requirements)
+  * [ulimits](#ulimits)
+* [Setup](#setup)
+  * [Mainnet (snap sync)](#mainnet-snap-sync)
+  * [Testnet (snap sync)](#testnet-snap-sync)
+
+---
+
+## Prerequisites
+
+This guide assumes you have the following software installed and are using Ubuntu 24.04 or newer. Running on other
+systems is possible, but may not be fully supported.
+
+- `git`
+- `jq`
+- `docker` and `docker-compose` (https://docs.docker.com/engine/install/ubuntu/)
+
+### System Requirements
+
+> [!IMPORTANT]
+> NVMe disks are highly recommended to ensure performance.
+
+| Profile    | CPU Cores | Memory | Disk |
+|------------|-----------|--------|------|
+| `hemi-min` | 2         | 12GiB  | 2TiB |
+
+> [!WARNING]
+> Over time, the amount of disk space required will grow. These values represent the current requirements (as of 2025),
+> with a buffer that should be sufficient for at least another year. It is highly recommended to monitor disk usage to
+> prevent the node from running out of disk space.
+
+### ulimits
+
+Certain components of the network require a very large number of open files. The Docker Compose file will attempt to
+change the necessary ulimits automatically.
+
+---
+
+## Setup
+
+> [!IMPORTANT]
+> This guide sets up snap-sync nodes, using the `hemi-min` Docker compose profile. The following components will run:
+>
+>  - `bssd` (Bitcoin Secure Sequencer)
+>  - `op-geth-l2` (Hemi L2 geth node)
+>  - `op-node` (Hemi L2 op-node)
+
+### Mainnet (snap sync)
+
+1. Clone the repository:
+    ```sh
+    git clone https://github.com/hemilabs/hemi-node.git
+    cd hemi-node 
+    ```
+
+2. Prepare the configuration files (**mainnet** with snap sync, hemi-min profile):
+    ```sh
+    ./scripts/gen.sh mainnet snap hemi-min
+    # gen: Generating files for mainnet (sync mode: snap, profile: hemi-min)
+    # gen: Generated ./mainnet/.env file
+    # gen: Generated random ./mainnet/jwt.hex file
+    # gen: Generated random ./mainnet/op-node-priv-key.txt file
+    # gen: Generated random ./mainnet/cookie file
+    # gen: Generated ./mainnet/entrypoint.sh
+    #
+    # gen: Setup complete! (mainnet, sync mode: snap, profile: hemi-min)
+    # gen:  ./scripts/gen.sh on Tue Oct 14 19:17:41 AEDT 2025 (version=v0.0.0 commit=d929f26 state=clean)
+    # gen:
+    # gen: Next steps:
+    # gen: 1. Configure your Ethereum RPC providers:
+    # gen:    - Edit mainnet/.env and add:
+    # gen:        GETHL1ENDPOINT=<your Ethereum RPC URL>
+    # gen:        PRYSMENDPOINT=<your Prysm RPC URL>
+    # gen:
+    # gen: 2. Start your node:
+    # gen:      cd mainnet
+    # gen:      docker compose --profile hemi-min up --build -d
+    # gen:
+    # gen: 3. Monitor your node:
+    # gen:      ./heminode.sh
+    ```
+
+3. Configure your Ethereum RPC providers:
+    - Edit `mainnet/.env` and add:
+      ```
+      GETHL1ENDPOINT=<YOUR_ETHEREUM_RPC_URL>
+      PRYSMENDPOINT=<YOUR_PRYSM_RPC_URL>
+      ```
+
+4. Start the node:
+    ```sh
+    cd mainnet
+    docker compose --profile hemi-min up --build -d
+    ```
+
+### Testnet (snap sync)
+
+1. Clone the repository:
+    ```sh
+    git clone https://github.com/hemilabs/hemi-node.git
+    cd hemi-node
+    ```
+
+2. Prepare the configuration files (**testnet** with snap sync, hemi-min profile):
+    ```sh
+    ./scripts/gen.sh testnet snap hemi-min
+    # gen: Generating files for testnet (sync mode: snap, profile: hemi-min)
+    # gen: Generated ./testnet/.env file
+    # gen: Generated random ./testnet/jwt.hex file
+    # gen: Generated random ./testnet/op-node-priv-key.txt file
+    # gen: Generated random ./testnet/cookie file
+    # gen: Generated ./testnet/entrypoint.sh
+    #
+    # gen: Setup complete! (testnet, sync mode: snap, profile: hemi-min)
+    # gen:  ./scripts/gen.sh on Tue Oct 14 19:17:41 AEDT 2025 (version=v0.0.0 commit=d929f26 state=clean)
+    # gen:
+    # gen: Next steps:
+    # gen: 1. Configure your Ethereum RPC providers:
+    # gen:    - Edit testnet/.env and add:
+    # gen:        GETHL1ENDPOINT=<your Ethereum RPC URL>
+    # gen:        PRYSMENDPOINT=<your Prysm RPC URL>
+    # gen:
+    # gen: 2. Start your node:
+    # gen:      cd testnet
+    # gen:      docker compose --profile hemi-min up --build -d
+    # gen:
+    # gen: 3. Monitor your node:
+    # gen:      ./heminode.sh
+    ```
+
+3. Configure your Ethereum RPC providers:
+    - Edit `testnet/.env` and add:
+      ```
+      GETHL1ENDPOINT=<YOUR_ETHEREUM_RPC_URL>
+      PRYSMENDPOINT=<YOUR_PRYSM_RPC_URL>
+      ```
+
+4. Start the node:
+    ```sh
+    cd testnet
+    docker compose --profile hemi-min up --build -d
+    ```
@@ -0,0 +1,54 @@
+# Hemi Node Setup
+
+This document is a guide to set up and run the Hemi stack with P2P nodes and RPC access. *This does not set up a
+batcher or sequencer.*
+
+> [!NOTE]
+> This guide is only for users looking to run a node on the Hemi Network, and is not required to use a wallet (e.g.
+> Rabby, Metamask, etc.) to interact with the Hemi Network, or run a PoP Miner.
+
+**Table of Contents**
+<!-- TOC -->
+* [Hemi Node Setup](#hemi-node-setup)
+  * [Prerequisites](#prerequisites)
+    * [System Requirements](#system-requirements)
+    * [ulimits](#ulimits)
+  * [Installation and setup](#installation-and-setup)
+<!-- TOC -->
+
+---
+
+## Prerequisites
+
+This guide assumes you have the following software installed and are using Ubuntu 24.04 or newer. Running on other
+systems is possible, but may not be fully supported.
+
+- `git`
+- `jq`
+- `docker` and `docker-compose-plugin` (https://docs.docker.com/engine/install/ubuntu/)
+
+### System Requirements
+
+> [!IMPORTANT]
+> NVMe disks are highly recommended to ensure performance.
+
+| Profile                                      | CPU Cores | Memory | Disk |
+|----------------------------------------------|-----------|--------|------|
+| [`full`](./profiles.md#profile-full)         | 8         | 40GiB  | 6TiB |
+| [`hemi`](./profiles.md#profile-hemi)         | 2         | 16GiB  | 3TiB |
+| [`hemi-min`](./profiles.md#profile-hemi-min) | 2         | 12GiB  | 2TiB |
+| [`l1`](./profiles.md#profile-l1)             | 6         | 24GiB  | 3TiB |
+
+> [!WARNING]
+> Over time, the amount of disk space required will grow. These values represent the current requirements (as of 2025),
+> with a buffer that should be sufficient for at least another year. It is highly recommended to monitor disk usage to
+> prevent the node from running out of disk space.
+
+### ulimits
+
+Certain components of the network require a very large number of open files. The Docker Compose file will attempt to
+change the necessary ulimits automatically.
+
+---
+
+## Installation and setup