94 lines
6.4 KiB
Markdown
94 lines
6.4 KiB
Markdown
# Kamado Pool — StartOS 0.4.0 Packaging
|
|
|
|
StartOS **0.4.0** wrapper for [Kamado Pool](../KamadoPool), a modern solo Bitcoin mining pool built on a patched fork of CKPool-solo with a Go middleware API and Svelte real-time dashboard.
|
|
|
|
This is the 0.4.0 port of the [0.3.5.1 wrapper](../KamadoPool-StartOS-0351), rebuilt on the TypeScript `@start9labs/start-sdk` and the revised 0.4.0 service architecture.
|
|
|
|
## What changed from the 0.3.5.1 package
|
|
|
|
| 0.3.5.1 | 0.4.0 |
|
|
|---|---|
|
|
| `manifest.yaml` + Deno `embassy.js` procedures | `startos/` TypeScript package on `@start9labs/start-sdk` (npm), bundled with ncc |
|
|
| Single container, `docker_entrypoint.sh` supervises ckpool + kamado-api + stunnel | One shared subcontainer, three daemons (`api`, `ckpool`, `stunnel`) + oneshots, individually health-checked and ordered by the SDK daemon runtime |
|
|
| Config form (`getConfig`/`setConfig`) writing `start9/config.yaml` | `store.json` file model + **Configure** action with input spec; settings changes restart daemons reactively |
|
|
| RPC credentials via config **pointers** to `bitcoind`/`bitcoind-testnet` | bitcoind **cookie** auth read from a read-only dependency mount; RPC/ZMQ reached over the LXC bridge address resolved reactively (no `.embassy` DNS) |
|
|
| Two dependency variants (`bitcoind`, `bitcoind-testnet`) | Single `bitcoind` dependency; the active chain is detected at runtime from `getblockchaininfo` (the coinbase self-test address is chosen accordingly) |
|
|
| No LAN TCP forwarding — users needed router forwards / simpleproxy for stratum | Stratum (and TLS stratum) exposed as **raw TCP host bindings**, directly reachable on the LAN. In-container ports are fixed constants; the configured value sets only the interface's `preferredExternalPort`, so a port change is a pure rebind that neither orphans a binding nor restarts the pool |
|
|
| `properties` for TLS fingerprint/PEM | **Stratum TLS Certificate** action (fingerprint + PEM, copyable) |
|
|
| Health checks: web / ckpool / bitcoin / submit-gap | Same four, plus an optional **ZMQ Block Feed** check, as daemon `ready` checks + standalone health checks |
|
|
| duplicity backup of both volumes | `sdk.setupBackups` of both volumes (`main`, `ckpool`) |
|
|
| compat migrations | `VersionGraph` with an `up` migration that converts a 0.3.5.1 `config.yaml` into `store.json` and preserves the SQLite DB, TLS cert, and ckpool state |
|
|
| — | i18n (en, es, de, pl, fr) for all user-facing strings |
|
|
|
|
Retained behavior: the ckpool restart loop gated on bitcoind reachability (now a daemon wrapper script), dual block-detection (ZMQ + 100 ms blockpoll), the loopback second stratum bind for TLS tagging (`server == 1` → lock icon), the v4 self-signed certificate with broad SANs, and ckpool loglevel 6 with `--log-shares`.
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js + npm**
|
|
- **Docker** with buildx
|
|
- **start-cli** — from the [StartOS packaging guide](https://docs.start9.com/packaging/0.4.0.x/environment-setup.html)
|
|
- **rsync**
|
|
- **KamadoPool source** — local sibling checkout at `../KamadoPool` (override with `KAMADO_SRC=/path/to/KamadoPool`)
|
|
|
|
## Building
|
|
|
|
```sh
|
|
npm ci # once — installs the SDK and bitcoin-core-startos (for typed dependency wiring)
|
|
make setup # once per boot — qemu binfmt + a multi-platform buildx builder
|
|
make # kamado-pool.s9pk — the universal package (ship this)
|
|
```
|
|
|
|
`make` produces a **universal `kamado-pool.s9pk`** carrying both the x86_64 and aarch64 images, so a single file installs on any StartOS machine. For faster iteration during development, `make x86` and `make arm` emit single-arch packages (`kamado-pool_x86_64.s9pk` / `kamado-pool_aarch64.s9pk`) and skip the other architecture entirely.
|
|
|
|
The Makefile syncs `../KamadoPool`'s `api/`, `ui/`, and `ckpool/` into `./kamado-src/` (gitignored) before packing; `start-cli s9pk pack` then builds the Docker image per architecture from the local `Dockerfile` (ckpool is cloned from the pinned upstream commit and patched with Kamado's patch series, the Svelte UI is embedded into the Go binary).
|
|
|
|
Only the ckpool stage and the runtime stage are built for the target architecture — the aarch64 half of those runs under qemu emulation on an x86 host, which is why `make setup` is required. The UI and API stages pin `--platform=$BUILDPLATFORM` and cross-compile instead: the Svelte build emits architecture-independent static assets, and `kamado-api` is `CGO_ENABLED=0` with a pure-Go SQLite driver, so `GOARCH` cross-compilation is exact and avoids emulating the two slowest stages.
|
|
|
|
**Note:** `start-cli s9pk pack` records a `gitHash` in the manifest and therefore requires this directory to be a git repository with at least one commit. Until you make one, you can point git at a throwaway repo just for the pack step:
|
|
|
|
```sh
|
|
git init /tmp/stub && cd /tmp/stub && touch .stub && git add .stub && git commit -m stub
|
|
GIT_DIR=/tmp/stub/.git make
|
|
```
|
|
|
|
**Troubleshooting:** if the Docker build fails with DNS errors like `lookup registry-1.docker.io … connection refused` from inside buildkit, your buildx builder container cannot resolve DNS (common with systemd-resolved hosts). The `network=host` driver option in `make setup` is what avoids this.
|
|
|
|
### Install to your server
|
|
|
|
Configure `~/.startos/config.yaml` with your server, then:
|
|
|
|
```sh
|
|
make install
|
|
```
|
|
|
|
Or sideload the produced `kamado-pool.s9pk` through the StartOS web UI.
|
|
|
|
### Overrides
|
|
|
|
```sh
|
|
make KAMADO_SRC=/path/to/KamadoPool
|
|
```
|
|
|
|
## Package layout
|
|
|
|
```text
|
|
startos/
|
|
manifest/ id, images (local Dockerfile build), volumes, bitcoind dependency
|
|
main.ts subcontainer, ckpool.conf + stunnel.conf rendering, daemons + health checks (fixed internal ports)
|
|
interfaces.ts Web UI (http 8080), Stratum (raw TCP, configurable), Stratum TLS (raw TCP, configurable + conditional)
|
|
fileModels/ store.json (service settings, incl. stratum ports)
|
|
actions/ Configure, Pool Status, Stratum TLS Certificate, Regenerate TLS Certificate, Reset Block Latency
|
|
dependencies.ts bitcoind (running, synced) + ZMQ autoconfig task
|
|
backups.ts volumes: main, ckpool
|
|
versions/ 0.2.0:3 with migration from the 0.3.5.1 wrapper
|
|
init/ store seeding, init ordering
|
|
i18n/ dictionaries (en, es, de, pl, fr)
|
|
assets/
|
|
scripts/ kamado-ckpool-run.sh (bitcoind wait + chain detect + exec ckpool), kamado-tls-init.sh (cert v4)
|
|
Dockerfile ckpool (patched) + Svelte UI + Go API + runtime stage
|
|
```
|
|
|
|
## License
|
|
|
|
GPL-3.0 — matches upstream Kamado and CKPool.
|