From 662440368895f7518152aa6ec56e744aeb11afe6 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 22 Oct 2026 15:10:44 +0200 Subject: [PATCH] Add Dockerfile and docker-compose.yml to run next to the Palladium node ElectrumX is built from this source tree with RocksDB and joins the external 'palladium' network of the node in palladiumcore/docker, reaching it as palladiumd:2332. RPC credentials come from .env (ignored by git, see .env.example). The Bitcoin-specific contrib/Dockerfile is removed. Co-Authored-By: Claude Sonnet 5.5 --- .dockerignore | 8 +++++++ .env.example | 7 +++++++ .gitignore | 2 ++ CLAUDE.md | 2 ++ Dockerfile | 52 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 20 ++++++++++++++++++ contrib/Dockerfile | 52 ---------------------------------------------- docker-compose.yml | 27 ++++++++++++++++++++++++ 8 files changed, 118 insertions(+), 52 deletions(-) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 Dockerfile delete mode 100644 contrib/Dockerfile create mode 100644 docker-compose.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..7f0db25 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +.git +.github +tests +docs +contrib +.env +*.pyc +__pycache__ diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..05b72c7 --- /dev/null +++ b/.env.example @@ -0,0 +1,7 @@ +# Copy to .env (never commit it). RPC credentials of the node: rpcuser/rpcpassword (or an rpcauth user) +# in ~/.palladium/palladium.conf. +PLM_RPC_USER=username +PLM_RPC_PASSWORD=change-me +#CACHE_MB=1200 +#REPORT_SERVICES=tcp://electrum.example.com:50001 +#ELECTRUMX_TCP_PORT=50001 diff --git a/.gitignore b/.gitignore index 98f2e4c..2b16e53 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ /src/e_x.egg-info/ /electrumx.egg-info/ /e_x.egg-info/ + +.env diff --git a/CLAUDE.md b/CLAUDE.md index 44c794a..55ef075 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,8 @@ DB_ENGINE=rocksdb DB_DIRECTORY=... DAEMON_URL=http://user:pass@host:port/ electr electrumx_rpc getinfo # talk to a running server via local RPC ``` +Docker: `docker compose up -d --build` (root `Dockerfile`, `docker-compose.yml`, `.env` from `.env.example`) runs the server on the external `palladium` network of the node in palladiumcore/docker, daemon at `palladiumd:2332`. + Configuration is entirely via environment variables, parsed in `src/electrumx/server/env.py` (documented in `docs/environment.rst`). `DB_ENGINE` is mandatory in 2.0 (`leveldb` or `rocksdb`). Python >=3.10; free-threaded 3.14t is experimental. ## Architecture diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..1a78126 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,52 @@ +# plm-electrumx: ElectrumX server for Palladium, with RocksDB, built from this source tree. +# +# docker compose up -d --build (see docker-compose.yml and README.md) +# +# Runs on the "palladium" network of the node in palladiumcore/docker and reaches it as palladiumd:2332. + +FROM python:3.14-trixie AS builder + +WORKDIR /usr/src/app + +# the libs needed by rocksdb (including development headers) +RUN apt-get update \ + && apt-get -y --no-install-recommends install \ + build-essential \ + librocksdb-dev \ + pkg-config \ + && rm -rf /var/lib/apt/lists/* + +COPY pyproject.toml README.md LICENCE MANIFEST.in ./ +COPY src ./src +RUN python -m venv venv \ + && venv/bin/pip install --no-cache-dir ".[rocksdb]" + + +FROM python:3.14-slim-trixie + +# the libs needed by rocksdb (no development headers or statics) +RUN apt-get update && apt-get -y --no-install-recommends install librocksdb9.10 && rm -rf /var/lib/apt/lists/* + +ENV COIN=Palladium +ENV NET=mainnet +ENV DB_ENGINE=rocksdb +ENV DB_DIRECTORY=/var/lib/electrumx +ENV SERVICES="tcp://:50001" +# set at run time, see docker-compose.yml: +#ENV DAEMON_URL="http://user:password@palladiumd:2332/" +#ENV CACHE_MB=2000 +#ENV REPORT_SERVICES=tcp://example.com:50001 + +WORKDIR /usr/src/app +COPY --from=builder /usr/src/app/venv ./venv + +# the data directory is created here so that an empty volume is owned by the electrumx user +RUN useradd --create-home --uid 1000 electrumx \ + && mkdir -p "$DB_DIRECTORY" && chown electrumx:electrumx "$DB_DIRECTORY" +USER electrumx +VOLUME /var/lib/electrumx + +# 50001: Electrum protocol over TCP. +EXPOSE 50001 + +CMD ["/usr/src/app/venv/bin/electrumx_server"] diff --git a/README.md b/README.md index c74a1c9..c9a8355 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,26 @@ the history of arbitrary addresses. ## Running +### With Docker (next to the node of palladiumcore) + +ElectrumX joins the `palladium` network created by the node in +[palladiumcore/docker](https://github.com/palladium-coin/palladiumcore/tree/docker-node/docker) and reaches it +as `palladiumd:2332`. RPC and ZMQ of the node are not published on the host, so nothing else is exposed. + +1. Start the node (`docker compose up -d` in `palladiumcore/docker`). Its `~/.palladium/palladium.conf` needs + `server=1` and `txindex=1` (no `prune`). +2. `cp .env.example .env` and set `PLM_RPC_USER` / `PLM_RPC_PASSWORD` to the RPC credentials of that file + (use a dedicated `rpcauth` user for anything public). +3. `docker compose up -d --build` + +The first start builds the database from the node from genesis, which takes a while; follow it with +`docker compose logs -f electrumx`. The database is the `electrumx-db` volume. Electrum clients connect to +TCP port 50001 (`ELECTRUMX_TCP_PORT` in `.env`). To announce a public server to the network, set +`REPORT_SERVICES` in `.env`. Settings are in `.env` and `docker-compose.yml`; the image defaults are in the +`Dockerfile`. + +### Without Docker + Requirements: Python >= 3.10, a synced Palladium node with `server=1` and `txindex=1` (no pruning), and one of the DB engines (`pip install ".[leveldb]"` or `pip install ".[rocksdb]"`). diff --git a/contrib/Dockerfile b/contrib/Dockerfile deleted file mode 100644 index 7c321ba..0000000 --- a/contrib/Dockerfile +++ /dev/null @@ -1,52 +0,0 @@ -# ElectrumX for Bitcoin, with RocksDB -# This is a simple ~minimal example Dockerfile. -# -# Build: docker build --pull -t electrumx . -# podman build --pull -t electrumx . -# Run: docker run -d --net=host -v ~/electrumx-db:/var/lib/electrumx -e DAEMON_URL="http://youruser:yourpass@localhost:8332" -e REPORT_SERVICES=tcp://example.com:50001 electrumx -# podman run -d --net=host -v ~/electrumx-db:/var/lib/electrumx -e DAEMON_URL="http://youruser:yourpass@localhost:8332" -e REPORT_SERVICES=tcp://example.com:50001 electrumx -# Stop: docker stop CONTAINER_ID -# podman stop CONTAINER_ID - -FROM python:3.14-trixie AS builder - -WORKDIR /usr/src/app - -# Install the libs needed by rocksdb (including development headers) -RUN apt-get update \ - && apt-get -y --no-install-recommends install \ - build-essential \ - git \ - librocksdb-dev \ - pkg-config \ - && rm -rf /var/lib/apt/lists/* - -# Install ElectrumX -ARG ELECTRUMX_VERSION=2.0.0 -#ARG ELECTRUMX_VERSION=b8f6e227f251fe5cba96b940ffaa094439636417 -RUN python -m venv venv \ - && venv/bin/pip install --no-cache-dir \ - "e_x[rocksdb] @ git+https://github.com/spesmilo/electrumx.git@${ELECTRUMX_VERSION}" - - -FROM python:3.14-slim-trixie - -# Install the libs needed by rocksdb (no development headers or statics) -RUN apt-get update && apt-get -y --no-install-recommends install librocksdb9.10 && rm -rf /var/lib/apt/lists/* - -ENV SERVICES="tcp://:50001" -ENV COIN=Bitcoin -ENV DB_DIRECTORY=/var/lib/electrumx -ENV DAEMON_URL="http://username:password@hostname:port/" -ENV ALLOW_ROOT=true -ENV DB_ENGINE=rocksdb -#ENV CACHE_MB=2000 - -WORKDIR /usr/src/app -COPY --from=builder /usr/src/app . - -VOLUME /var/lib/electrumx - -RUN mkdir -p "$DB_DIRECTORY" - -CMD ["/usr/src/app/venv/bin/python", "/usr/src/app/venv/bin/electrumx_server"] diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..572af14 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,27 @@ +# ElectrumX for Palladium, next to the node of palladiumcore/docker. +# Start the node first: it creates the "palladium" network. Setup and usage: README.md +services: + electrumx: + build: . + image: plm-electrumx + restart: unless-stopped + environment: + # the node is reached by name on the shared network; user and password are those of its palladium.conf + DAEMON_URL: http://${PLM_RPC_USER}:${PLM_RPC_PASSWORD}@palladiumd:2332/ + CACHE_MB: ${CACHE_MB:-1200} + # address announced to other servers and clients, if this server is public (tcp://host:50001) + REPORT_SERVICES: ${REPORT_SERVICES:-} + ports: + - "${ELECTRUMX_TCP_PORT:-50001}:50001" + volumes: + - electrumx-db:/var/lib/electrumx + stop_grace_period: 2m # lets the server flush the db on shutdown + networks: [palladium] + +volumes: + electrumx-db: + +networks: + palladium: + name: palladium + external: true