Skip to content

Run the node from a prebuilt binary in Docker, configured from .env - #366

Merged
SDL-A1 merged 3 commits into
Rustock-dev:mainfrom
ida3m0n:docker-deployment-pr
Nov 18, 2026
Merged

SDL-A1 merged 3 commits into
Rustock-dev:mainfrom
ida3m0n:docker-deployment-pr

Conversation

@ida3m0n

@ida3m0n ida3m0n commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Run a node under Docker Compose from a prebuilt binary, so servers need Docker and not Rust. Setup: build the binary, copy it with docker-compose.yml, docker/ and .env.example, set .env, docker compose up -d --build. Full guide in docs/docker.md.

Stacked on #365. The first commit is that PR; this one is the second. The diff shrinks once #365 merges.

What it adds

  • scripts/build-binary.sh <amd64|arm64> builds rustock-cli and the maintenance tools through docker/build.Dockerfile, which exports only the binaries. Output goes to dist/ with .sha256 files.
  • A small runtime image (debian:bookworm-slim, non-root uid 10001) runs the binary, which Compose mounts from ./bin/rustock-cli. Compose refuses to start if the binary is missing.
  • docker/entrypoint.sh turns .env into flags and fails with a clear message on a bad port, network id, IPv4 address, non-writable data directory, or discovery port other than P2P + 1.
  • RPC and metrics are published on 127.0.0.1 only. Docker logs rotate. restart: on-failure, so a clean rsk_shutdown stays stopped.
  • docs/docker.md covers install and rollback, ports, data directory, logs, stop, importing an rskj database, and the maintenance tools.

Relation to the existing Dockerfile

The root Dockerfile (#348) is untouched: it stays the self-contained image. The build stage lives in docker/build.Dockerfile. .dockerignore keeps its rules and adds paths the build never needs (data, dist, bin, docs, tools, *.md except README.md). The README gets a pointer to the new guide.

The build image is Debian bookworm (glibc 2.36); the root Dockerfile uses Ubuntu 22.04 (glibc 2.35). The two images are independent, but I can align them on Ubuntu 22.04 if you prefer one base.

External IP

RUSTOCK_EXTERNAL_IP is optional: on mainnet and testnet the node now looks its address up (#365). The entrypoint requires an IPv4 address when one is set. Behind NAT, set it and forward the P2P TCP port and the discovery UDP port (P2P + 1).

Known limits (documented)

  • The running node ignores SIGTERM, so docker compose stop ends in SIGKILL after 30 s. The clean stop is rsk_shutdown, which needs --rpc-admin.
  • docker/node.toml uses the epoch trie backend because single aborts on an empty data directory. An imported rskj database needs --trie-backend single.

Verification

  • Entrypoint: 11 cases run in a debian:bookworm-slim container against a stub binary (defaults, explicit IP, IPv6, out-of-range octet, leading zero, private IPv4, testnet ports, discovery mismatch, bad port, extra args).
  • docker/node.toml loads with the current binary (unknown keys are rejected).
  • docker compose config renders; bash -n passes on both scripts.
  • Not done in this PR's checks: a full docker buildx build of the binary and a container start on the rebased tree. An earlier revision of this setup ran an rskj import and then followed the mainnet tip on a server.

scripts/build-binary.sh builds rustock-cli and the maintenance tools for amd64
or arm64 through docker/build.Dockerfile, which exports only the binaries. A
small runtime image runs the binary, which docker-compose.yml mounts from
./bin, with settings taken from .env and checked by docker/entrypoint.sh.

The root Dockerfile is unchanged: it stays the self-contained image, and
.dockerignore keeps its rules and adds the paths the build never needs.

RUSTOCK_EXTERNAL_IP is optional, because on mainnet and testnet the node looks
its address up when it is unset. The entrypoint requires an IPv4 address when
one is given, matching the node.
@SDL-A1
SDL-A1 merged commit bc248b8 into Rustock-dev:main Nov 18, 2026
7 checks passed
ColbySerpa pushed a commit to HORNET-Storage/Rustock that referenced this pull request Nov 18, 2026
The repository already said to screen foreign code before reading it for correctness. It did not say how, and the how is the part that matters: cargo build and cargo test execute a contributor's code as the developer, with their SSH keys, their gh token and write access to /var/lib/rustock, before a line has been read. The node in production runs hardened under systemd; the development machine does not. Merging was never the dangerous step.

Adds three questions answerable from the diff alone -- new [[package]] entries in Cargo.lock, build-time surfaces (build.rs, .cargo/config.toml, rust-toolchain.toml, proc macros), and non-Rust executables. All three clean means reading the diff is the whole review. Any one dirty means the build belongs in a throwaway container, whoever the author appears to be.

Singles out .cargo/config.toml because it is the quietest: a runner, linker or alias there is arbitrary command execution that reads as configuration rather than code. This repository has none, so one appearing in a pull request is a flag by itself. Also notes that rust-analyzer runs build.rs and expands proc macros when a project is opened, so an editor is an execution vector too.

Written while reviewing Rustock-dev#365 and Rustock-dev#366, which the checklist was then applied to: Rustock-dev#365 came out clean on all three, Rustock-dev#366 dirty on the third, and the four Docker and shell files were read line by line as a result.

The .gitignore entries are unrelated housekeeping: the SPV wallet lives outside this tree, and these are a second line of defence. Root-anchored so a crate directory named client or server is unaffected, and the /dist/ and /bin/ entries from Rustock-dev#366 are preserved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ColbySerpa added a commit to HORNET-Storage/Rustock that referenced this pull request Nov 18, 2026
Upstream's four pull requests since 169ef57: the external IP looked up
over HTTPS when --external-ip is not set (Rustock-dev#365), the node run from a
prebuilt binary in Docker and configured from .env (Rustock-dev#366), libz-sys
moved past its heap-overflow advisory (Rustock-dev#367), and CLAUDE.md on
screening an outside pull request without running it (Rustock-dev#373).

Three files conflicted:

- crates/cli/Cargo.toml: both sides added tokio-rustls (ring, tls12)
  and webpki-roots, upstream's for the external-IP lookup and this
  branch's for --import. They are listed once, under one comment for
  both, beside this branch's serde_json and sha2. Cargo.lock gains no
  package over upstream's.
- deny.toml: both sides rewrote the note on webpki-roots' licence. It
  now names every use: the external-IP lookup, Rootstock's server for
  --import, a stable minimum gas price's web source, and lettre under
  the smtp feature.
- crates/cli/src/main.rs: both sides' modules are kept.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants