The node is built once into a binary. A small runtime image runs it, with the
binary mounted from ./bin. Servers need Docker, not Rust.
Rustock is an unaudited prototype: run it on testnet or beside rskj first.
| File | Role |
|---|---|
scripts/build-binary.sh |
builds rustock-cli and the maintenance tools for amd64 or arm64 |
docker/build.Dockerfile |
the build stage; exports only the binary |
docker/runtime.Dockerfile |
the runtime image |
docker-compose.yml |
runs it, configured from .env |
docker/node.toml |
node settings that are the same everywhere |
The Dockerfile in the repository root is a separate, self-contained image;
Compose does not use it.
scripts/build-binary.sh amd64 # or arm64Writes dist/rustock-0.1.0-<commit>-linux-<arch> and
dist/rustock-tools-0.1.0-<commit>-linux-<arch>.tar.gz, each with a .sha256
file, and -dirty appended for uncommitted changes. FEATURES=smtp enables
peg-out alert email. TOOLS="rewind_to block_info" overrides the tool list.
Build each architecture on matching hardware; emulated builds are very slow (RocksDB, LTO). Outside Docker the binary needs the glibc of Debian bookworm or newer.
Copy the binary, its .sha256 file, docker-compose.yml, .env.example and
docker/ to the server. uname -m is x86_64 for amd64, aarch64 for arm64.
sha256sum -c rustock-0.1.0-<commit>-linux-amd64.sha256
mkdir -p bin
install -m 755 rustock-0.1.0-<commit>-linux-amd64 bin/.rustock-cli.new
mv bin/.rustock-cli.new bin/rustock-cli
cp .env.example .env # set RUSTOCK_EXTERNAL_IP behind NAT
docker compose up -d --build
docker compose logs -f rustockWithout bin/rustock-cli Compose refuses to start. To roll back, install the
previous binary and recreate the container.
A fresh start syncs mainnet from genesis, which takes days.
RUSTOCK_EXTRA_ARGS=--snap-sync joins from a recent state instead.
docker/node.toml selects the epoch trie backend because the default
single backend aborts on an empty data directory ("This database has no trie
in it"). epoch keeps only recent state, so historical queries below its
retention window fail.
| Port | Purpose | Published on | Setting |
|---|---|---|---|
| 5050/tcp | peers | all interfaces | RUSTOCK_P2P_PORT |
| 5051/udp | discovery | all interfaces | RUSTOCK_DISCOVERY_PORT |
| 4444/tcp | JSON-RPC | 127.0.0.1 | RUSTOCK_RPC_BIND, RUSTOCK_RPC_PORT |
| 9898/tcp | metrics | 127.0.0.1 | RUSTOCK_METRICS_BIND, RUSTOCK_METRICS_PORT |
- Open the peer and discovery ports in the firewall. On mainnet and testnet the
node looks up its public IPv4 address at start (
--ip-check-url, set throughRUSTOCK_EXTRA_ARGS;offdisables it). Behind NAT the lookup returns the outbound address, so setRUSTOCK_EXTERNAL_IPand forward both ports. With no address and no lookup the node advertises127.0.0.1. - The node binds discovery to the peer port + 1, so
RUSTOCK_DISCOVERY_PORTmust equalRUSTOCK_P2P_PORT + 1. The container refuses to start otherwise. - 5050 is rskj's mainnet port. For testnet use
RUSTOCK_NETWORK_ID=31,RUSTOCK_P2P_PORT=50505andRUSTOCK_DISCOVERY_PORT=50506. - Publishing on
127.0.0.1keeps other hosts out only on Docker Engine 28.3.3 or later. - The node has no RPC authentication. Put an authenticating proxy in front of any RPC port that leaves a trusted network.
.env holds per-server settings; .env.example documents
each. docker/node.toml holds the rest; node.example.toml
documents every setting. Flags from .env override the file, and an unknown
key in it is an error.
| Changed | Run |
|---|---|
.env |
docker compose up -d |
bin/rustock-cli, docker/node.toml |
docker compose up -d --force-recreate |
docker/entrypoint.sh, docker/runtime.Dockerfile |
docker compose up -d --build |
Recreating the container kills a running node; stop it first (see Stop).
RUSTOCK_DATA_DIR holds the database, the node key and file logs.
| Value | Meaning |
|---|---|
rustock-data (default) |
Docker named volume |
path starting with / or ./ |
host directory |
A host directory must be owned by uid 10001, or the container refuses to start:
sudo install -d -o 10001 -g 10001 /srv/rustockdocker compose down -v deletes a named volume: the chain and the node key. An
imported mainnet database is about 154 GB; use local SSD.
By default the node logs to stdout: docker compose logs -f rustock. Docker
rotates them at RUSTOCK_LOG_MAX_SIZE and RUSTOCK_LOG_MAX_FILE, about 500 MB
in total by default. RUSTOCK_LOG_LEVEL accepts per-module directives such as
info,rustock_sync=debug; a RUST_LOG variable in the container overrides it.
RUSTOCK_LOG_TO_STDOUT=false writes rustock.log.<date> into the data
directory, one file a day, never pruned. The log directory cannot be set
separately from the data directory.
The running node ignores SIGTERM, so docker compose stop waits 30 seconds and
then kills it. For a clean stop, set RUSTOCK_EXTRA_ARGS=--rpc-admin and call
rsk_shutdown, which flushes the trie store and exits 0. The container then
stays stopped; docker compose up -d starts it again. The admin methods have
no authentication.
docker compose exec rustock bash -c '
body="{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"rsk_shutdown\",\"params\":[]}"
exec 3<>/dev/tcp/127.0.0.1/4444
printf "POST / HTTP/1.1\r\nHost: x\r\nContent-Type: application/json\r\nContent-Length: ${#body}\r\nConnection: close\r\n\r\n%s" "$body" >&3
cat <&3'Stop rskj, then import the directory that contains blocks/ and unitrie/,
mounted read-only. receipts/, blooms/ and stateRoots/ are not needed. The
importer opens the datasources as RocksDB, so check that dbKind.properties
says keyvalue.datasource=ROCKS_DB.
docker compose run --rm -v /var/lib/rsk/database/mainnet:/import:ro rustock \
--import-rskj /import --import-skip-metadata
docker compose run --rm rustock --metadata-in-memoryWithout --import-skip-metadata the import rebuilds the metadata itself by
walking parent hashes, which takes hours. The import also keeps running after
a Ctrl-C: it skips to compaction instead of stopping. Detach from the terminal
rather than interrupting it, and restart from an empty data directory if it was
interrupted, because re-importing over a partial one needs room for both copies.
The import writes the state trie into the node's own database, which the
epoch backend refuses to start against. Set
RUSTOCK_EXTRA_ARGS=--trie-backend single before the next start. That backend
keeps every historical state version, so the database grows without bound.
Offline programs from crates/cli/examples/, shipped in the tools tarball. The
node must be stopped: they take the database lock.
| Tool | Does |
|---|---|
rewind_to <dir> <block> |
resets the heads to <block>; the node re-syncs the tail |
set_exec_head <dir> <block> [--dry-run] |
moves the executed head to a canonical block |
reset_exec_head <dir> |
replays execution from genesis, keeping downloaded blocks |
block_info <dir> <height>... |
prints stored block metadata |
height_peek <dir> <from> [to] |
lists every block stored at a height |
mkdir -p bin/tools && tar -xzf rustock-tools-<version>-linux-amd64.tar.gz -C bin/tools
docker compose run --rm tools rewind_to /var/lib/rustock <block>The tools run in the image built by docker compose up -d --build. Check
set_exec_head with --dry-run first. rewind_to needs the state at the
target block in the database.
The health check opens a TCP connection to the metrics port, so it shows that the process serves, not that it is synced. Sync progress:
curl -s localhost:9898/metrics | grep -E 'rustock_(peers|sync_height|sync_target_height) 'Metrics are listed in metrics.md and alerting is configured in alerts.md.