Run a Native Node (Docker)

TL;DR

Pull the image, mount a data directory with your CKB private key, and start the container. In under a minute you'll have a Fiber node running on Testnet — no Rust toolchain required.

docker run --rm -d \
  --name fiber-node \
  -e FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' \
  -v "$(pwd)/fiber-node:/fiber" \
  -p 8228:8228 \
  nervos/fiber:0.9.0-rc7

Prerequisites

• Docker (v20.10 or newer) installed and running
• A CKB private key (generate one with ckb-cli or export from an existing wallet)
• Basic understanding of command line operations

Running Your Node

1. Pull the Docker Image

The Fiber image is published to two registries:

# From Docker Hub
docker pull nervos/fiber:0.9.0-rc7

# Or from GHCR
docker pull ghcr.io/nervosnetwork/fiber:0.9.0-rc7

Check Docker Hub or GHCR for available tags. For production, pin a specific version tag (e.g. 0.9.0-rc7) to avoid unexpected upgrades.

2. Prepare the Data Directory

Create a local directory to hold the node's configuration, database, and key material:

mkdir -p ./fiber-node/ckb

Place your CKB private key at ./fiber-node/ckb/key. If you already have a key exported by ckb-cli, copy the first line of the extended privkey file:

head -n 1 ./ckb/exported-key > ./fiber-node/ckb/key

3. Run the Container

Start the node with the following command:

mkdir -p ./fiber-node/ckb
# Place your CKB private key in ./fiber-node/ckb/key

docker run --rm -it \
  --name fiber-node \
  -e FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' \
  -e RUST_LOG='info' \
  -v "$(pwd)/fiber-node:/fiber" \
  -p 8228:8228 \
  nervos/fiber:0.9.0-rc7

Expected Output: You should see log lines indicating the node is starting, connecting to bootnodes, and syncing with the Testnet. Press Ctrl+C to stop the node (add -d instead of -it to run in detached mode).

4. Environment Variables

The container reads its configuration through the following environment variables:

5. Use Mainnet Configuration

By default the container starts on Testnet. To run on Mainnet, point FIBER_CONFIG_TEMPLATE to the bundled mainnet template:

docker run --rm -it \
  --name fiber-node \
  -e FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' \
  -e FIBER_CONFIG_TEMPLATE='/usr/local/share/fiber/config/mainnet/config.yml' \
  -v "$(pwd)/fiber-node:/fiber" \
  -p 8228:8228 \
  nervos/fiber:0.9.0-rc7

6. Interact with the Node

Use docker exec to run fnn-cli commands inside the running container:

# Check node info
docker exec -it fiber-node fnn-cli info

# List channels
docker exec -it fiber-node fnn-cli channel list_channels

# Interactive mode
docker exec -it fiber-node fnn-cli

7. Expose RPC (Advanced)

By default the RPC endpoint listens on 127.0.0.1:8227 inside the container and is not mapped to the host. If you need external access, edit config.yml in your data directory to set rpc.listening_addr to 0.0.0.0:8227, then map the port when starting the container:

docker run --rm -it \
  --name fiber-node \
  -e FIBER_SECRET_KEY_PASSWORD='YOUR_PASSWORD' \
  -v "$(pwd)/fiber-node:/fiber" \
  -p 8228:8228 \
  -p 8227:8227 \
  nervos/fiber:0.9.0-rc7

Once the RPC port is mapped, you can call the JSON-RPC interface directly from the host:

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"node_info"}' \
  http://127.0.0.1:8227/

8. Build the Image Locally

If you want to build from source — for example to test an unreleased branch — clone the repository and build the image:

git clone https://github.com/nervosnetwork/fiber.git
cd fiber
docker build -f docker/Dockerfile -t fiber:local .

Then run the locally built image using fiber:local instead of nervos/fiber:0.9.0-rc7.

9. Data Migration

When upgrading from older versions that require explicit storage migration, run the migration tool against your data directory:

docker run --rm -it \
  -v "$(pwd)/fiber-node:/fiber" \
  nervos/fiber:<0.8.x-release-tag> \
  fnn-migrate -d /fiber

Replace <0.8.x-release-tag> with the exact version you are upgrading from (no v prefix, e.g. 0.8.0). After migration completes, start the node with the new image as usual.

Next Steps

• Basic Transfer — send your first payment
• Config Reference — full configuration options