Skip to content

Commit bc97992

Browse files
MattDHillMattDHill
committed
makefile, contributing, readme, workflows
1 parent 341d009 commit bc97992

File tree

12 files changed

+353
-121
lines changed

12 files changed

+353
-121
lines changed

‎.github/workflows/buildService.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,4 @@ jobs:
2020
# with:
2121
# FREE_DISK_SPACE: true
2222
secrets:
23-
DEV_KEY: ${{ secrets.DEV_KEY }}
23+
DEV_KEY: ${{ secrets.DEV_KEY }}

‎.github/workflows/releaseService.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,11 @@ jobs:
1010
uses: start9labs/shared-workflows/.github/workflows/releaseService.yml@master
1111
with:
1212
# FREE_DISK_SPACE: true
13-
REGISTRY: ${{ vars.REGISTRY }} # Optional. Defaults to https://alpha-registry-x.start9.com
13+
REGISTRY: ${{ vars.REGISTRY }}
14+
S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }}
1415
secrets:
15-
DEV_KEY: ${{ secrets.DEV_KEY }} # Required
16+
DEV_KEY: ${{ secrets.DEV_KEY }}
17+
S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
18+
S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
1619
permissions:
17-
contents: write
20+
contents: write

‎CONTRIBUTING.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Contributing
2+
3+
## Building and Development
4+
5+
See the [StartOS Packaging Guide](https://docs.start9.com/packaging-guide/) for complete environment setup and build instructions.
6+
7+
### Quick Start
8+
9+
```bash
10+
# Install dependencies
11+
npm ci
12+
13+
# Build universal package
14+
make
15+
```

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
# overrides to s9pk.mk must precede the include statement
21
ARCHES := x86 arm
2+
# overrides to s9pk.mk must precede the include statement
33
include s9pk.mk

‎README.md‎

Lines changed: 250 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,253 @@
11
<p align="center">
2-
<img src="icon.png" alt="Project Logo" width="21%">
2+
<img src="icon.png" alt="Public Pool Logo" width="21%">
33
</p>
44

5-
# Public Pool for StartOS
5+
# Public Pool on StartOS
6+
7+
> **Upstream docs:** <https://github.com/benjamin-wilson/public-pool#readme>
8+
>
9+
> Everything not listed in this document should behave the same as upstream
10+
> Public Pool v0.2.5. If a feature, setting, or behavior is not mentioned
11+
> here, the upstream documentation is accurate and fully applicable.
12+
13+
[Public Pool](https://github.com/benjamin-wilson/public-pool) is an open source Bitcoin mining pool with a Stratum server and web UI.
14+
15+
---
16+
17+
## Table of Contents
18+
19+
- [Image and Container Runtime](#image-and-container-runtime)
20+
- [Volume and Data Layout](#volume-and-data-layout)
21+
- [Installation and First-Run Flow](#installation-and-first-run-flow)
22+
- [Configuration Management](#configuration-management)
23+
- [Network Access and Interfaces](#network-access-and-interfaces)
24+
- [Actions (StartOS UI)](#actions-startos-ui)
25+
- [Dependencies](#dependencies)
26+
- [Backups and Restore](#backups-and-restore)
27+
- [Health Checks](#health-checks)
28+
- [Limitations and Differences](#limitations-and-differences)
29+
- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
30+
- [Contributing](#contributing)
31+
- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)
32+
33+
---
34+
35+
## Image and Container Runtime
36+
37+
| Property | Value |
38+
|----------|-------|
39+
| Image | Custom Dockerfile (multi-stage build from upstream source) |
40+
| Base | `node:20-bookworm-slim` + nginx |
41+
| Architectures | x86_64, aarch64 (emulated) |
42+
43+
The image is built from source, compiling both the backend (public-pool) and frontend (public-pool-ui) with StartOS-specific patches applied to the UI.
44+
45+
---
46+
47+
## Volume and Data Layout
48+
49+
| Volume | Mount Point | Purpose |
50+
|--------|-------------|---------|
51+
| `main` | various | All Public Pool data |
52+
53+
**Key paths on the `main` volume:**
54+
55+
- `.env` — environment configuration file
56+
- `store.json` — persists Stratum display address
57+
- `mainnet/` — mainnet database (mounted to `/public-pool/DB`)
58+
- `testnet/` — testnet database (mounted to `/public-pool/DB`)
59+
60+
**Bitcoin dependency mount:**
61+
62+
- `/mnt/bitcoind` — Bitcoin Core volume (read-only, for cookie auth)
63+
64+
---
65+
66+
## Installation and First-Run Flow
67+
68+
| Step | Upstream | StartOS |
69+
|------|----------|---------|
70+
| Installation | Docker Compose | Install from marketplace |
71+
| Configuration | Edit `.env` file manually | Auto-configured, tunable via action |
72+
| Bitcoin Core | Manual RPC setup | Auto-configured via dependency |
73+
| Network | Single network only | Switchable between mainnet and testnet |
74+
75+
**First-run steps:**
76+
77+
1. Ensure Bitcoin Core (or Bitcoin Testnet) is installed
78+
2. Install Public Pool from the StartOS marketplace
79+
3. Optionally run "Configure" to set a custom pool identifier
80+
4. Point your mining hardware at the Stratum interface
81+
82+
---
83+
84+
## Configuration Management
85+
86+
### Auto-Configured by StartOS
87+
88+
| Setting | Value | Purpose |
89+
|---------|-------|---------|
90+
| `BITCOIN_RPC_URL` | `http://bitcoind.startos` | Bitcoin RPC (mainnet) |
91+
| `BITCOIN_RPC_PORT` | `8332` / `48332` | RPC port (mainnet/testnet) |
92+
| `BITCOIN_RPC_COOKIEFILE` | `/mnt/bitcoind/.cookie` | Cookie auth |
93+
| `BITCOIN_ZMQ_HOST` | `tcp://bitcoind.startos:28332` | ZMQ notifications |
94+
| `BITCOIN_RPC_TIMEOUT` | `10000` | RPC timeout (ms) |
95+
| `API_PORT` | `3334` | Internal API port |
96+
| `STRATUM_PORT` | `3333` | Stratum protocol port |
97+
| `API_SECURE` | `false` | API security |
98+
99+
### Configurable via Actions
100+
101+
| Setting | Action | Default | Purpose |
102+
|---------|--------|---------|---------|
103+
| Pool Identifier | Configure | `Public-Pool` | Coinbase transaction identifier |
104+
| Server Display URL | Configure | Auto-detected IPv4 | Homepage display address |
105+
| Network | Switch Network | mainnet | Toggle mainnet/testnet |
106+
107+
---
108+
109+
## Network Access and Interfaces
110+
111+
| Interface | Port | Protocol | Purpose |
112+
|-----------|------|----------|---------|
113+
| Web UI | 80 | HTTP | Pool dashboard and statistics |
114+
| Stratum Server | 3333 | TCP | Mining protocol |
115+
116+
**Access methods (StartOS 0.4.0):**
117+
118+
- LAN IP with unique port
119+
- `<hostname>.local` with unique port
120+
- Tor `.onion` address
121+
- Custom domains (if configured)
122+
123+
---
124+
125+
## Actions (StartOS UI)
126+
127+
### Configure
128+
129+
| Property | Value |
130+
|----------|-------|
131+
| ID | `config` |
132+
| Visibility | Enabled |
133+
| Availability | Any status |
134+
| Purpose | Set pool identifier and display URL |
135+
136+
**Inputs:**
137+
138+
- **Pool Identifier** — ASCII text included in Coinbase transactions (max 100 chars)
139+
- **Server Display URL** — the address shown on your pool's homepage (auto-populated from available interfaces)
140+
141+
### Switch Network
142+
143+
| Property | Value |
144+
|----------|-------|
145+
| ID | `set-network` |
146+
| Visibility | Enabled |
147+
| Availability | Any status |
148+
| Purpose | Toggle between mainnet and testnet |
149+
150+
Dynamically shows "Switch to testnet" or "Switch to mainnet" based on current configuration. Includes a confirmation warning.
151+
152+
---
153+
154+
## Dependencies
155+
156+
| Dependency | Required | Version | Purpose | Auto-Config |
157+
|------------|----------|---------|---------|-------------|
158+
| Bitcoin Core | Optional | >=29.1 | Mainnet mining | ZMQ enabled |
159+
| Bitcoin Testnet | Optional | >=29.1 | Testnet mining | ZMQ enabled |
160+
161+
One of the two Bitcoin dependencies is required depending on the selected network. StartOS creates a critical task to enable ZMQ on the active Bitcoin node.
162+
163+
---
164+
165+
## Backups and Restore
166+
167+
**Included in backup:**
168+
169+
- `main` volume — configuration, database, and state
170+
171+
**Restore behavior:**
172+
173+
- All mining history and configuration restored
174+
- Service resumes normal operation
175+
176+
---
177+
178+
## Health Checks
179+
180+
| Check | Display Name | Grace Period | Messages |
181+
|-------|--------------|-------------|----------|
182+
| Stratum | Stratum Server | 15s | Ready / Not ready |
183+
| Web UI | Web Interface | Default | Ready / Not ready |
184+
185+
---
186+
187+
## Limitations and Differences
188+
189+
1. **Custom Docker image** — built from source with UI patches for display URL injection
190+
2. **Single network** — cannot mine on mainnet and testnet simultaneously (switchable via action)
191+
3. **Architecture emulation** — aarch64 builds use emulation
192+
193+
---
194+
195+
## What Is Unchanged from Upstream
196+
197+
- Full Stratum protocol support
198+
- Mining statistics and dashboard
199+
- Block discovery tracking
200+
- Worker management
201+
- Coinbase transaction customization
202+
- All web UI features
203+
204+
---
205+
206+
## Contributing
207+
208+
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and development workflow.
209+
210+
---
211+
212+
## Quick Reference for AI Consumers
213+
214+
```yaml
215+
package_id: public-pool
216+
upstream_version: 0.2.5
217+
image: custom (dockerBuild from upstream source)
218+
architectures: [x86_64, aarch64]
219+
volumes:
220+
main:
221+
.env: environment configuration
222+
store.json: stratum display address
223+
mainnet/: mainnet database
224+
testnet/: testnet database
225+
ports:
226+
ui: 80
227+
stratum: 3333
228+
api: 3334 (internal)
229+
dependencies:
230+
bitcoind:
231+
required: false (one of bitcoind or bitcoind-testnet required)
232+
min_version: ">=29.1"
233+
enforced_config: [zmqEnabled=true]
234+
bitcoind-testnet:
235+
required: false
236+
min_version: ">=29.1"
237+
enforced_config: [zmqEnabled=true]
238+
actions:
239+
- config (enabled, any)
240+
- set-network (enabled, any)
241+
health_checks:
242+
- stratum: port_listening 3333 (15s grace)
243+
- ui: port_listening 80
244+
backup_volumes:
245+
- main
246+
startos_managed_config:
247+
BITCOIN_RPC_TIMEOUT: "10000"
248+
API_PORT: "3334"
249+
STRATUM_PORT: "3333"
250+
API_SECURE: "false"
251+
not_available:
252+
- Simultaneous mainnet and testnet mining
253+
```

‎package-lock.json‎

Lines changed: 6 additions & 33 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,10 @@
77
},
88
"dependencies": {
99
"@start9labs/start-sdk": "^0.4.0-beta.48",
10-
"bitcoind-startos": "git+https://github.com/Start9Labs/bitcoind-startos.git#update/040",
11-
"js-yaml": "^4.1.1"
10+
"bitcoind-startos": "git+https://github.com/Start9Labs/bitcoind-startos.git#update/040"
1211
},
1312
"devDependencies": {
1413
"@types/node": "^22.19.7",
15-
"@types/js-yaml": "^4.0.9",
1614
"@vercel/ncc": "^0.38.4",
1715
"prettier": "^3.8.1",
1816
"typescript": "^5.9.3"

‎startos/install/versions/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
export { v_0_2_5_1 as current } from './v0.2.5.1'
1+
export { v_0_2_5_2_b0 as current } from './v0.2.5.2.b0'
22
export const other = []

0 commit comments

Comments
 (0)