Add three new named health checks to the manifest alongside the existing
web check, each implemented as a fetch+parse of /api/health:
ckpool — is the stratum server alive? (miners can connect)
bitcoin — is Bitcoin Core RPC reachable? (blocks can be submitted)
submit-gap — have all block submissions been confirmed by bitcoind?
The web check retains its current role: calling /api/health which returns
503 when any critical subsystem is down, so StartOS marks the overall
service as degraded. The three new checks give operators a drill-down
view of which subsystem is the problem.
Each check returns "starting" for the first 20 s after launch so normal
boot sequencing does not trigger false alarms.
Companion to KamadoPool's df5e65d. The fallback submitter has been
scrapped — primary bitcoind remains the sole submission target, with
upstream's indefinite-retry behavior preserved. Drops the
block-broadcast-fallback union from advanced config and the
BACKUP_RPC_URLS / PENDING_BLOCKS_DIR / PENDING_BLOCKS_GRACE exports
from docker_entrypoint.
ckpool patch 0004 now bounds generator_submitblock's wait for a live
primary to ~3s rather than spinning indefinitely, and calls submit
before writing the pending-block hex to disk so the happy path adds
zero latency. The right default is small: a fallback should kick in
while the work is still relevant for the current chain tip.
Range widened to [1, 600] so impatient operators can crank further
down. Description updated to reflect the new architecture.
New advanced.block-broadcast-fallback union:
* enabled (default: false)
* grace-seconds (default: 30, range 10-600)
* backup-rpcs: list of full bitcoind RPC URLs, with inline
credentials supported (https://user:pass@host:port/). Up to 10.
docker_entrypoint reads the list with yq, joins with newlines, and
exports BACKUP_RPC_URLS plus PENDING_BLOCKS_DIR=<logdir>/pending-blocks
and PENDING_BLOCKS_GRACE so kamado-api's blocksubmit watcher activates.
If the user enables the fallback but provides no URLs, we log a
warning and disable rather than spam pending-block warnings.
The companion ckpool patch (KamadoPool repo, 0004-dump-pending-block-
for-fallback) writes raw block hex to PENDING_BLOCKS_DIR before each
submit attempt and unlinks on success. The watcher only fires if
ckpool's primary submit fails AND the operator configured backup RPCs.
Two related polish items:
1. Optional custom block explorer. New union under Advanced config
("Block Explorer") defaulting to "mempool.space". Picking
"Custom URL" reveals a single text field where the user can
point Kamado at their own mempool instance — useful for users
running mempool as a sibling StartOS service or on the same LAN.
The entrypoint reads .advanced.mempool-explorer.{type,url} and
exports MEMPOOL_BASE_URL when type=custom; otherwise leaves it
empty and the UI keeps its mempool.space defaults.
2. stunnel debug level 4 (warning) was hiding successful TLS
handshakes — only failures showed up in the service logs, which
made it hard to confirm "yes, my miner did connect over TLS"
without going looking at netstat. Bump to level 5 (notice) so
each successful handshake produces an "accepted connection from
<ip>" / "connected from <ip>" line. Errors stay visible at level
3, so the only thing this changes is making the happy path
observable.
AxeOS / Bitaxe firmware verifies the stratum TLS cert against
Espressif's bundled Mozilla CA store. A self-signed cert never
matches anything in that bundle, so the handshake fails with
mbedtls_ssl_handshake -0x3000 (fatal alert) and the miner shows
"Failed to verify certificate". The firmware does, however, expose
a "Stratum SSL Cert" field where a custom CA / trusted root can be
pasted — that's the supported way to use TLS with a self-signed
pool cert.
Read tls/stratum.crt from the main volume and surface the full PEM
(BEGIN/END markers included) as a copyable property. Update the
TLS port and fingerprint descriptions to point users at the new
field with a clear "paste this into your miner's TLS settings"
explanation, instead of the previous wording that implied
disabling cert verification was the only path.
Entrypoint persists the generated TLS cert fingerprint so the
properties script can read it from the main volume. The screen
shows the active network, plaintext and TLS stratum ports, the
SHA-256 fingerprint for miner pinning, and the worker username
format (BTC address plus optional worker label).
Worker stratum username is the payout address in ckpool-solo, so the
separate field was redundant. Niche vardiff/logging/zmq knobs now
live under an Advanced group with sensible defaults.
New 'tls' union config (disabled by default) spins up an
stunnel4 process inside the container that terminates TLS on
a configurable port (3334 by default) and forwards decrypted
stratum traffic to 127.0.0.1:${STRATUM_PORT}.
Cert is self-signed, generated once on first start with a
10-year validity and persisted at /root/.kamado/tls/ so the
fingerprint stays stable across restarts. SHA-256 fingerprint
is printed to container logs on each startup so users can
pin it on their miners. Miners must connect with
verification disabled (no CA trust chain for a private pool).
Runtime image grows by ~3MB for stunnel4 + openssl. The
supervisor loop now waits on three PIDs and tears all of them
down together if any one exits.
New 'zmq-enabled' boolean (default true) makes the entrypoint
export BITCOIN_ZMQ_BLOCK=tcp://<bitcoind-host>:28332, which
kamado-api's zmqmon subscribes to for sub-second chain refresh
on the dashboard. Disable it if your bitcoind doesn't have
zmqpubhashblock exposed.
The 1-arg form tried to call effects.createDir which doesn't
exist in the 0.3.5.1 effects API, crashing config save with
'TypeError: effects.createDir is not a function'. The 3-arg
form (effects, newConfig, deps) just wires up dependencies
based on the chosen bitcoind variant without touching the
filesystem.
Exposes stratum-port in the StartOS config UI so users running
simpleproxy or another TCP forwarder can point Kamado at a
non-default port. Entrypoint substitutes the value into
ckpool.conf serverurl.
Also pins placeholder KAMADO_SHA in the Dockerfile — swap to a
real pushed commit before the first build.
Multi-stage Dockerfile clones KamadoPool at a pinned SHA, builds
ckpool and kamado-api (with embedded Svelte UI), runtime image
supervises both processes via tini + wait -n. Config covers
bitcoind mainnet/testnet4 variant, payout address, coinbase tag,
vardiff knobs, and log level. Web UI interface only — stratum
:3333 requires a router port-forward or simpleproxy workaround
because StartOS 0.3.x does not forward raw TCP on LAN.
TODO before first build: pin KAMADO_REPO + KAMADO_SHA in the
Dockerfile to a pushed commit.
satoshi