Run a Gravity Testnet Public Full Node With Docker

Run a Gravity Longevity Testnet (L1) Public Full Node with Docker. Covers image preparation, testnet artifacts, PFN identity generation, pruning, startup, sync checks, and operational cleanup.

This guide walks you through running a Gravity Longevity Testnet Public Full Node (PFN) with the gravity_node Docker image. A PFN syncs from an upstream public-network seed and can serve EVM JSON-RPC for applications, indexers, or internal services.

Gravity Longevity Testnet is an L1 network with Chain ID 7771625. A PFN does not participate in consensus, does not hold validator stake, and does not require validator invite access. If you only need occasional testnet reads or writes, you can use the public endpoint at https://testnet-rpc.gravity.xyz instead.

Required version. Longevity Testnet nodes must run v1.10.0-pre (or newer) to follow the live tip after Gamma. See Gravity Longevity Testnet Hardforks.

Placeholders. Commands below use <YOUR_...> placeholders. Replace each value before running. Never commit generated identities, private keys, .env files, rendered node config, logs, or node databases to version control.

Prerequisites

1. Docker and Docker Compose v2. Production-like nodes should run on Linux. Docker Desktop on macOS is useful for local validation, but it handles host networking differently from Linux.

2. Local command-line tools. Install just, envsubst from GNU gettext, jq, curl, nc, and lsof.

3. The Gravity SDK repository. The Docker image and config templates live in gravity-sdk.

   git clone https://github.com/Galxe/gravity-sdk.git
   cd gravity-sdk
   git checkout v1.10.0-pre

4. Testnet genesis.json and waypoint.txt. These artifacts pin the exact chain you are joining. Download the canonical files from gravity-sdk/genesis/testnet.

5. An upstream public-network seed. The current public testnet PFN seed is shown below.

6. SSD/NVMe storage. Chain data grows with uptime. Budget well above the current chain size.

1. Pull the Docker Image

docker pull ghcr.io/galxe/gravity_node:v1.10.0-pre

To build from source instead, check out v1.10.0-pre and tag the image ghcr.io/galxe/gravity_node:v1.10.0-pre so the .env values below still match:

DOCKER_BUILDKIT=1 docker build --network=host \
  -f docker/gravity_node/Dockerfile \
  -t ghcr.io/galxe/gravity_node:v1.10.0-pre \
  --build-arg CARGO_PROFILE=release \
  .

2. Prepare the Docker Workspace

cd docker/gravity_node
cp .env.example .env
mkdir -p config

Edit .env:

GRAVITY_IMAGE=ghcr.io/galxe/gravity_node
IMAGE_TAG=v1.10.0-pre
RUST_LOG=info

The container reads node config from ./config and stores chain data in Docker volumes.

3. Prepare Testnet Artifacts

From docker/gravity_node:

mkdir -p ../../cluster/output
curl -fsSL https://raw.githubusercontent.com/Galxe/gravity-sdk/main/genesis/testnet/genesis.json \
  -o ../../cluster/output/genesis.json
curl -fsSL https://raw.githubusercontent.com/Galxe/gravity-sdk/main/genesis/testnet/waypoint.txt \
  -o ../../cluster/output/waypoint.txt

Copy these artifacts into the Docker config directory:

cp ../../cluster/output/genesis.json config/genesis.json
cp ../../cluster/output/waypoint.txt config/waypoint.txt

4. Gather Seed Information

Use the public testnet PFN host as the upstream seed.

Node	Host	JSON-RPC endpoint	Public-network seed port	Peer ID	Network public key
testnet-rpc-p2p-1	testnet-rpc-p2p-1.gravity.xyz	https://testnet-rpc.gravity.xyz	6195	e7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433	86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a

Before using the seed, verify from your node host that the public-network port is reachable:

nc -vz testnet-rpc-p2p-1.gravity.xyz 6195

Use the current public testnet PFN seed when rendering PFN_SEEDS_BLOCK in the Docker config section below:

seeds = [
  { peer_id = "e7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433", role = "PreferredUpstream", address = "/dns/testnet-rpc-p2p-1.gravity.xyz/tcp/6195/noise-ik/86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a/handshake/0" },
]

For normal JSON-RPC traffic, use the aggregate public RPC endpoint:

https://testnet-rpc.gravity.xyz

5. Generate a PFN Identity

Create a minimal cluster config file for identity generation, for example cluster/local-testnet-pfn-docker.toml:

[cluster]
name = "<YOUR_TESTNET_PFN_CLUSTER_NAME>"

[[nodes]]
id = "local-testnet-pfn-docker"
role = "pfn"
identity = { source = "file" }

The Docker flow uses this TOML only to generate node identity material. It does not read ports, seeds, base_dir, or data_dir from the TOML during container startup. Docker runtime storage is controlled by the volume or bind mount in the start command, and by the container paths rendered in the next section.

Generate the PFN identity:

cd ../../cluster
just init local-testnet-pfn-docker.toml
cd ../docker/gravity_node
cp ../../cluster/output/local-testnet-pfn-docker/config/identity.yaml config/identity.yaml

The generated identity.yaml contains private node identity material. Keep it on the runtime host only.

6. Render Container Config

The container sees config at /gravity/config and data at /gravity/data, so the rendered files must use container paths, not host paths.

DATA_DIR, STORAGE_DIR, and LOG_DIR are intentionally separate:

/gravity/data/              # Docker data volume root
└── data/                   # STORAGE_DIR, chain databases
    ├── consensus_db/
    ├── quorumstoreDB/
    └── reth/

/gravity/logs/              # Docker logs volume root
├── consensus_log/
└── execution_logs/

To place data on a specific host disk, mount that host path to /gravity/data. To place logs on a specific host disk, mount that host path to /gravity/logs. Do not change the TOML data_dir for Docker runtime storage.

From docker/gravity_node:

export NODE_ID=local-testnet-pfn-docker
export HOST=127.0.0.1
export PUBLIC_PORT=26195
export RPC_PORT=28545
export METRICS_PORT=29001
export INSPECTION_PORT=30001
export AUTHRPC_PORT=28661
export P2P_PORT_RETH=32024
export TXPOOL_MAX_ACCOUNT_SLOTS=64
export PRUNE_TRANSACTIONLOOKUP_DISTANCE=10064

export CONFIG_DIR=/gravity/config
export DATA_DIR=/gravity/data
export STORAGE_DIR=/gravity/data/data
export LOG_DIR=/gravity/logs
export GENESIS_PATH=/gravity/config/genesis.json

export RPC_HTTP_CORSDOMAIN='*'
export RPC_HTTP_API='debug,eth,net,trace,txpool,web3,rpc'

export NETWORK_IDENTITY_TYPE=from_file
export NETWORK_IDENTITY_FIELD=path
export NETWORK_IDENTITY_VALUE=/gravity/config/identity.yaml
export SAFETY_RULES_IDENTITY_VARIANT=from_file
export SAFETY_RULES_IDENTITY_KEY=identity_blob_path
export SAFETY_RULES_IDENTITY_VALUE=/gravity/config/identity.yaml
export DISCOVERY_METHOD_FULLNODE_BLOCK=''
export PFN_SEEDS_BLOCK='    seeds:
      "0xe7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433":
        addresses:
          - "/dns/testnet-rpc-p2p-1.gravity.xyz/tcp/6195/noise-ik/86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a/handshake/0"
        role: PreferredUpstream'

envsubst < ../../cluster/templates/public_full_node.yaml.tpl \
  > config/public_full_node.yaml

envsubst < ../../cluster/templates/reth_config_pfn_prune.json.tpl \
  > config/reth_config.json

If you do not want transaction-lookup pruning, do not set PRUNE_TRANSACTIONLOOKUP_DISTANCE, and render reth_config.json from the non-prune template instead:

envsubst < ../../cluster/templates/reth_config_pfn.json.tpl \
  > config/reth_config.json

Verify the rendered config:

jq . config/reth_config.json >/dev/null
grep -n 'public_full_node.yaml\|prune.transactionlookup.distance\|gravity/config\|gravity/data' \
  config/reth_config.json
grep -n 'PreferredUpstream\|testnet-rpc-p2p-1.gravity.xyz\|/gravity/config/identity.yaml' \
  config/public_full_node.yaml

Expected reth_config.json behavior:

• chain points to /gravity/config/genesis.json;

• gravity_node_config points to /gravity/config/public_full_node.yaml;

• datadir points to /gravity/data/data/reth;

• log.file.directory points to /gravity/logs/execution_logs/;

• when pruning is enabled, prune.transactionlookup.distance is 10064.

7. Pruning Mode

prune_transactionlookup_distance = 10064 starts reth with transaction-lookup pruning enabled. This keeps recent transaction-hash lookup data while allowing older lookup indexes to be pruned.

Use a value greater than or equal to 10064 for production-like PFN/RPC nodes. Treat smaller values as test-only and reject them during config review.

Use this pruning mode when you want lower execution database growth and do not need arbitrary old eth_getTransactionByHash lookups from this node.

If you omit prune_transactionlookup_distance, the generated PFN reth config uses archive-style transaction lookup behavior and keeps historical lookup indexes instead of pruning them. That is simpler for indexers or debugging flows that need old transaction hashes, but it uses more disk over time.

Do not set prune_transactionlookup_distance = 0 to disable pruning. A distance of 0 is still a pruning mode and can prune transaction lookup data aggressively. To run without transaction-lookup pruning, leave the field out.

8. Optional: Warm Start From a Snapshot or Existing Node

A new Docker PFN can sync from genesis, but that may take a long time on an established testnet. To warm start, load the snapshot into the Docker data volume before the first node start.

If the Docker PFN has already started once, stop the container and remove the old data volume before importing a snapshot. Do not merge snapshot files into an already-initialized database.

The Docker container mounts its data volume at /gravity/data. The chain databases must live under /gravity/data/data, so extract snapshot contents into that data subdirectory.

Option A: Download the Public Testnet Data Snapshot

Gravity publishes daily Longevity Testnet PFN data snapshots. List dates, then download. For example, use 2026-09-01 for gravity-testnet-data/2026-09-01.tar:

curl -s 'https://storage.googleapis.com/storage/v1/b/gravity-public-bucket/o?prefix=gravity-testnet-data/&fields=items(name,size,updated)' \
  | jq -r '.items[] | "\(.name) \(.size) \(.updated)"'

SNAPSHOT_DATE=2026-09-01   # or a newer date from the list above
curl -L --fail --continue-at - \
  "https://storage.googleapis.com/gravity-public-bucket/gravity-testnet-data/${SNAPSHOT_DATE}.tar" \
  -o "/tmp/${SNAPSHOT_DATE}.tar"

The snapshot tar contains database directories such as consensus_db/, quorumstoreDB/, and reth/ at the archive root. It does not contain an outer data/ directory.

For the Linux compose flow, load the snapshot into the compose data volume:

docker compose run --rm --no-deps \
  --user root \
  --entrypoint sh \
  -e SNAPSHOT_DATE \
  -v /tmp:/snapshot:ro \
  gravity_node \
  -lc 'mkdir -p /gravity/data/data && \
       tar -xf "/snapshot/${SNAPSHOT_DATE}.tar" -C /gravity/data/data && \
       chown -R 10001:10001 /gravity/data /gravity/logs'

For the macOS docker run flow, load the snapshot into the explicit named volume used by the start command below:

set -a
. ./.env
set +a

docker volume create gravity_node_testnet_pfn_data
docker volume create gravity_node_testnet_pfn_logs
docker run --rm \
  --user root \
  --entrypoint sh \
  -e SNAPSHOT_DATE \
  -v gravity_node_testnet_pfn_data:/gravity/data \
  -v gravity_node_testnet_pfn_logs:/gravity/logs \
  -v /tmp:/snapshot:ro \
  ${GRAVITY_IMAGE}:${IMAGE_TAG} \
  -lc 'mkdir -p /gravity/data/data && \
       tar -xf "/snapshot/${SNAPSHOT_DATE}.tar" -C /gravity/data/data && \
       chown -R 10001:10001 /gravity/data /gravity/logs'

After extraction, the Docker data volume should contain:

/gravity/data/data/consensus_db/
/gravity/data/data/quorumstoreDB/
/gravity/data/data/reth/

Option B: Copy From an Existing Node You Control

If you already run a trusted RPC/PFN, you can copy only the chain databases from that node:

cd <YOUR_EXISTING_NODE_DATA_DIR>
tar -cf /tmp/testnet-pfn-data.tar consensus_db quorumstoreDB reth

Then load /tmp/testnet-pfn-data.tar into the Docker data volume with the same compose or docker run extraction pattern above. Mount /tmp as /snapshot and replace the extraction command with:

tar -xf /snapshot/testnet-pfn-data.tar -C /gravity/data/data

Do not copy rand_db or secure_storage.json from another node. Those files carry node-specific randomness or safety state and should not be reused.

9. Start the PFN

Make sure the selected host ports are free:

lsof -nP -iTCP:26195 -iTCP:28545 -iTCP:29001 -iTCP:30001 -iTCP:28661 -iTCP:32024

On Linux, use Docker Compose:

docker compose up -d
docker ps --filter name=gravity_node

The compose file uses network_mode: host because p2p ports need predictable advertised addresses.

On Docker Desktop for macOS, host networking behaves differently. For local validation from the macOS host, use explicit port publishing:

docker rm -f gravity_node 2>/dev/null || true
set -a
. ./.env
set +a

docker run -d --name gravity_node --restart unless-stopped \
  -p 26195:26195 \
  -p 28545:28545 \
  -p 29001:29001 \
  -p 30001:30001 \
  -p 28661:28661 \
  -p 32024:32024 \
  -v "$(pwd)/config:/gravity/config:ro" \
  -v gravity_node_testnet_pfn_data:/gravity/data \
  -v gravity_node_testnet_pfn_logs:/gravity/logs \
  -e RUST_BACKTRACE=1 \
  -e RUST_LOG=info \
  --ulimit nofile=1048576:1048576 \
  ${GRAVITY_IMAGE}:${IMAGE_TAG}

10. Verify Sync

Confirm that your local Docker PFN is on the testnet chain:

curl -s --noproxy '*' http://127.0.0.1:28545 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq -r .result

The expected result is 0x7695e9, which is decimal 7771625.

Query the local Docker PFN:

curl -s --noproxy '*' http://127.0.0.1:28545 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq -r .result

Compare with the public RPC:

curl -s --noproxy '*' https://testnet-rpc.gravity.xyz \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq -r .result

When the two heights are close and your local height keeps advancing, the node is caught up. Gravity has BFT-final blocks: once a block is returned by your node, there is no EVM-style reorg to wait for.

Follow logs:

docker logs gravity_node -f
docker exec gravity_node sh -lc \
  'tail -n 200 /gravity/logs/execution_logs/*/reth.log'
docker exec gravity_node sh -lc \
  'tail -n 200 /gravity/logs/consensus_log/vfn.log'

Confirm the prune config was accepted:

docker exec gravity_node sh -lc \
  'grep -R "Pruner initialized\\|prune_config\\|transaction_lookup" /gravity/logs/execution_logs || true'

11. Stop, Restart, or Reset

For the Linux compose flow, stop the container but keep chain data:

docker compose down

Restart:

docker compose up -d

Delete the local PFN database and start from zero again:

docker compose down -v

For the macOS docker run flow, stop the container but keep chain data:

docker rm -f gravity_node

Delete the local PFN database and start from zero again:

docker rm -f gravity_node
docker volume rm gravity_node_testnet_pfn_data gravity_node_testnet_pfn_logs

Only remove Docker volumes when you intentionally want to delete the node database.

Files to Keep Out of Version Control

Do not commit generated runtime files:

• docker/gravity_node/.env;

• docker/gravity_node/config/*;

• cluster/output/<YOUR_NODE_ID>/config/identity.yaml;

• Docker volumes such as gravity-data, gravity-logs, gravity_node_testnet_pfn_data, and gravity_node_testnet_pfn_logs;

• node databases and logs.

The reusable materials are the public guide and SDK templates. Each operator should generate their own identity and runtime config.

See Also

• Gravity Longevity Testnet (L1)

• Gravity Longevity Testnet Hardforks

• Run a Gravity Testnet Public Full Node

• Run a Gravity Mainnet Public Full Node With Docker

• Node Providers