Skip to content

Add setup wizard, Docker orchestration, and UI improvements#16

Draft
warioishere wants to merge 7 commits intostratum-mining:mainfrom
warioishere:merge-wizard-and-create-docker-setup
Draft

Add setup wizard, Docker orchestration, and UI improvements#16
warioishere wants to merge 7 commits intostratum-mining:mainfrom
warioishere:merge-wizard-and-create-docker-setup

Conversation

@warioishere
Copy link

@warioishere warioishere commented Feb 26, 2026

⚠️ Scope Note

This PR combines multiple steps from #2 that were originally planned as separate PRs:

  • Port sv2-wizard components — add /setup route with mode selection and state detection
  • Docker setup — multi-stage Dockerfile, docker-compose.yml, Nginx config, and orchestration backend
  • Config & lifecycle endpoints — GET|POST /api/config, POST /api/restart, live log streaming via SSE

Ideally each would have been reviewed independently — apologies for the noise. The good news: everything discussed in Steps 1–3 is integrated and in a working, testable state. Changes are described in detail below. We'll be more disciplined about PR granularity going forward.

This PR is marked as draft, as it may change when upstream changes on sv2-apps are being made.


What's Included

1. Wizard Integration (sv2-wizard merge)

The sv2-wizard project has been integrated into this repo. It provides a step-by-step setup wizard that guides miners through connecting to an SV2 pool.

The wizard supports two modes:

  • Pool template mode — deploys a Translator Proxy only; SV1 miners connect via stratum+tcp
  • JD mode — deploys JD Client + optional Translator Proxy; requires a Bitcoin Core node for custom block templates. Native SV2 miners can skip the Translator Proxy entirely and connect directly to the JD Client.

I've also added my own pool (Blitzpool) to the pool list. SV2 integration will be merged soon so it can be used to test an SV2 Solo Mining Pool.


2. Docker Orchestration Backend

A Node.js/Express backend (server/) was added to orchestrate Docker containers:

Endpoint Description
POST /api/setup Pulls images, generates TOML configs from wizard data, starts tproxy and/or jd_client containers
GET /api/status Returns running state of each container
POST /api/restart Restarts a named container
GET|POST /api/config?service=jdc|tproxy Read/write TOML config files on disk
GET /api/logs?service=... Streams live container logs via SSE
GET|POST /api/wizard-data Persists the last completed wizard run so defaults are pre-filled on next run

Config files are generated from typed templates with sane defaults. The constructTemplates flag drives which components get deployed and how tProxy is wired — either directly to the pool, or through JDC at jd_client:34265.

JD Client and tProxy images are pulled directly from the StratumV2 Docker Hub repo.


3. UI Improvements

Settings Page — structured config forms with typed sub-tab forms for JD Client and Translator Proxy:

  • JD Client tabs: Basic, Keys, Mining, Upstreams (dynamic list), Template Provider, Logs
  • tProxy tabs: Basic, Mining, Upstreams (dynamic list), Difficulty, Logs

Config is read/written via GET|POST /api/config?format=json using smol-toml for parse/serialize.

Dashboard

  • Unified dashboard works in both JD mode and translator-only mode, showing which backends are active
  • Online indicators (🟢/🔴) for Translator and JD Client based on health polling

Wizard

  • Option to skip tProxy setup for native SV2 miners when setting up own template control
  • Added a Welcome Page with short explanations

4. Integrated Bitcoin Core Stack via Docker

When using JD mode, the wizard offers a one-click option to spin up a Docker-managed Bitcoin Core node with IPC support, pulled from the official image. This enables fully standalone deployments — no separately managed Bitcoin Core node required.

The Bitcoin Core container joins the same Docker network as the SRI components and shares the IPC socket via a volume mount.

The first option remains: setup with a local Bitcoin Core node.


5. Connection Details Page (/connect)

A new /connect page gives miners a single place to find their connection string after setup:

  • Reads wizard data and polls service health to determine what is actually running (tProxy, jd_client, or neither)
  • Shows the correct stratum+tcp://<host>:<port> endpoint for the active mode:
    • Port 34255 — SV1 miners via Translator Proxy
    • Port 34265 — native SV2 miners connecting directly to JD Client
  • Live animated indicators show which services are up
  • If no services are running, prompts the user to run the Setup Wizard first
  • Collapsible CPU Miner section (tProxy mode only) with step-by-step cpuminer instructions for users without an ASIC who want to test the stack

How to Test

Prerequisites: Docker and Docker Compose installed.

git clone <repo>
docker compose up --build

Then open http://localhost:2121 and:

  1. Navigate to /setup and run through the wizard
  2. Verify containers start, configs are generated, and the dashboard shows online indicators and hashrate
  3. Go to Settings → JD Client / Translator Proxy — edit a field, save, and confirm the .toml on disk reflects the change
  4. Navigate to /connect — verify the correct endpoint and port are shown for your deployed mode

Notes

Please feel free to point out any inappropriate changes — for example, adding my own pool or the welcome page. I'm aware this is a large diff, mainly due to integrating the wizard and adding the Docker orchestrator.

This is a proof of concept. Happy to hear feedback on the approach and split things into separate PRs once we've sorted out any fundamental issues or messy code.

warioishere and others added 4 commits February 26, 2026 08:32
- Integrate sv2-wizard with pool connection flow, Bitcoin Core setup,
  translator proxy and JD client configuration, and deployment result
- Add Docker orchestration backend (Dockerode) for container lifecycle
- Add wizard intro page with Stratum logo and SV2 path explainers
- Add IPC socket path input with host-level verify check
- Add Update tab to JDC and tProxy settings (SSE-based image pull)
- Add health-based redirect to /setup for first-time users
- Self-host Inter and JetBrains Mono fonts via fontsource
When re-running the wizard and going through a step that was skipped
in a prior run, the old skipped_<step> flag persisted because updateData
only merges. Now handleContinue explicitly sets the flag to false for
skippable steps, so deployedTproxy and other consumers pick up the
correct state.
Resolve two issues that prevented tProxy from starting in JD mode:

1. Replace Docker hostname with container IP in translator config — the
   translator proxy binary only accepts IP addresses, not hostnames,
   causing AddrParseError on startup.

2. Use JDC's authority key instead of the pool's in the translator
   config — in JD mode the translator connects to JDC, not the pool,
   so the Noise handshake needs JDC's keypair.

Also patches the update route to keep the translator config in sync
when either container is recreated.
@warioishere
Copy link
Author

warioishere commented Feb 26, 2026

Still got some problems connecting tproxy to jd-client, upstream bug from jd-client?

11:25:20 — Initial connection succeeds (both sides):

tProxy:
INFO Connected to upstream at 172.19.0.2:34265
INFO SetupConnectionSuccess(used_version: 2)
INFO Extension negotiation success: supported=[2]
INFO Translator Proxy: listening on 0.0.0.0:34255

JDC:
INFO New downstream connection socket_address=172.19.0.5:41010
INFO SetupConnection(vendor: SRI, hardware_version: Translator Proxy)
INFO Extension negotiation success: requested=[2], negotiated=[2]

11:30:20 — Connection drops after 5 minutes, JDC tries to rebind and FAILS:

JDC:
WARN Writer task exited.
WARN Downstream: unified message loop exited.
INFO Starting downstream server at 0.0.0.0:34265
ERROR Failed to bind downstream server at 0.0.0.0:34265 error=Os { code: 98, kind: AddrInUse, message: "Address already in use" }

After the first downstream disconnects, JDC tries to restart its listener but the old socket is still bound (EADDRINUSE). The stale listener accepts new TCP connections, but JDC's internal state has been reset, so every subsequent handshake fails immediately.

Edit: pulled the latest images of jd-client and tproxy from dockerhub.

@warioishere warioishere marked this pull request as draft February 26, 2026 11:41
pavlenex and others added 3 commits February 26, 2026 15:43
- Entrypoint: persist mining address to file for bitcoin-node (no wallet module)
- getRegtestInfo: read saved address, estimate balance from block count
- mineRegtestBlocks: use generatetodescriptor (works without wallet)
- getBlockchainInfo: add -testnet4/-regtest flag so bitcoin-cli connects
  to the correct RPC port instead of defaulting to mainnet 8332
- Hide misleading sync progress panel for regtest (always shows IBD
  due to synthetic block timestamps)
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.

2 participants