Skip to content

chore: rename config files (minimal + reference) #326

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VijitSingh97 merged 2 commits into from
Jul 1, 2026
Merged

chore: rename config files (minimal + reference) #326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
72a161e
chore: rename config files for clarity (minimal + reference)
VijitSingh97 Jun 29, 2026
c0d14de
Merge branch 'develop' into chore/config-rename
VijitSingh97 Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,11 @@ An interactive setup script takes you from clone to mining in a few minutes.
# Grab the latest release — pulls the published, tested images (no local build)
curl -fsSL https://github.com/p2pool-starter-stack/pithead/releases/latest/download/pithead.tar.gz | tar xz
cd pithead
cp config.json.template config.json # then set your Monero + Tari payout addresses
cp config.minimal.json config.json # then set your Monero + Tari payout addresses
./pithead setup
```

> For every tunable, copy `config.advanced.example.json` instead. To build from source (a `dev`
> For every tunable, copy `config.reference.json` instead. To build from source (a `dev`
> build), e.g. to contribute, see [Install from source](docs/getting-started.md#alternative-build-from-source).

> NOTE: Prereqs are Ubuntu Server 24.04 LTS, 16 GB+ RAM, an SSD (~300 GB pruned / ~500 GB full
Expand Down
0 config.json.template → config.minimal.json
View file
Open in desktop
File renamed without changes.
0 config.advanced.example.json → config.reference.json
View file
Open in desktop
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Only your two wallet addresses are required. Every other key is optional and fal
the node runs locally, on the `main` pool, with a secure dashboard, and the local node's RPC
credentials are auto-generated. Leave a key out unless you want to change it.

A fresh `config.json` is just this (see [`config.json.template`](../config.json.template)):
A fresh `config.json` is just this (see [`config.minimal.json`](../config.minimal.json)):

```json
{
Expand All @@ -23,7 +23,7 @@ A fresh `config.json` is just this (see [`config.json.template`](../config.json.
```

For the full shape with every key and its default, see
[`config.advanced.example.json`](../config.advanced.example.json) and copy in only the keys you
[`config.reference.json`](../config.reference.json) and copy in only the keys you
want to override.

> The string `"auto"` anywhere means "let the stack pick the default": a default path, the
Expand Down
10 changes: 5 additions & 5 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ process; most of it runs on its own.
> ```bash
> curl -fsSL https://github.com/p2pool-starter-stack/pithead/releases/latest/download/pithead.tar.gz | tar xz
> cd pithead
> cp config.json.template config.json # set your Monero + Tari payout addresses
> cp config.minimal.json config.json # set your Monero + Tari payout addresses
> ./pithead setup
> ```
>
Expand Down Expand Up @@ -55,11 +55,11 @@ dashboard shows the real version and the update-checker works:
```bash
curl -fsSL https://github.com/p2pool-starter-stack/pithead/releases/latest/download/pithead.tar.gz | tar xz
cd pithead
cp config.json.template config.json # then set your Monero + Tari payout addresses
cp config.minimal.json config.json # then set your Monero + Tari payout addresses
```

`config.json.template` is minimal: just your two payout addresses. `setup` fills in defaults for
everything else. For the full set of knobs, copy `config.advanced.example.json` instead. Have your
`config.minimal.json` is minimal: just your two payout addresses. `setup` fills in defaults for
everything else. For the full set of knobs, copy `config.reference.json` instead. Have your
Monero and Tari payout addresses ready (Tari wallets are sometimes labeled Minotari, same thing).

### Alternative: build from source
Expand All @@ -71,7 +71,7 @@ stack, clone the repo. pithead sees the `build/` context and builds locally, tag
```bash
git clone https://github.com/p2pool-starter-stack/pithead.git
cd pithead && chmod +x pithead
cp config.json.template config.json # then set your payout addresses
cp config.minimal.json config.json # then set your payout addresses
```

> Changed your mind later? You can convert a clone to the published images in place. See
Expand Down
2 changes: 1 addition & 1 deletion docs/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ What exists today:
(the bundle ships no Dockerfiles, just `pithead` + `VERSION` + compose + the config templates + the
`./build` runtime mounts) resolves `STACK_VERSION` to `vX.Y.Z` and pulls the published images
(`--pull missing`; `upgrade` forces a re-pull). Override with `PITHEAD_REGISTRY` / `PITHEAD_PULL`. So
a release is now `cp config.json.template config.json && ./pithead setup`, no local build.
a release is now `cp config.minimal.json config.json && ./pithead setup`, no local build.

**Remaining:**

Expand Down
4 changes: 2 additions & 2 deletions pithead
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1468,7 +1468,7 @@ check_prerequisites() {
log "All dependencies satisfied."
}

# Placeholder credentials shipped in config.json.template / config.advanced.example.json. We
# Placeholder credentials shipped in config.minimal.json / config.reference.json. We
# treat them like empty values so a user who copies the template but never edits the node creds
# still gets real, auto-generated ones (rather than working-but-predictable defaults).
readonly PLACEHOLDER_NODE_USER="create_a_username_for_node"
Expand Down Expand Up @@ -1520,7 +1520,7 @@ ensure_config_exists() {
[ -f "$CONFIG_FILE" ] && return 0

if [ ! -t 0 ]; then
error "$CONFIG_FILE not found and no interactive terminal is available.\n Create it first (copy config.json.template to config.json and edit it), then re-run."
error "$CONFIG_FILE not found and no interactive terminal is available.\n Create it first (copy config.minimal.json to config.json and edit it), then re-run."
fi

log "$CONFIG_FILE not found. Starting interactive setup..."
Expand Down
8 changes: 4 additions & 4 deletions scripts/release.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,13 +466,13 @@ compose_build_mounts() {
# containers find the config templates they render at setup.
make_bundle() {
# Unpacks to a versionless "pithead/" dir so the documented quick start can `cd pithead` and so a
# later bundle re-download upgrades it in place. Ships BOTH config templates: config.json.template
# later bundle re-download upgrades it in place. Ships BOTH config templates: config.minimal.json
# (basic — just the two wallet addresses, the documented quick-start config) and the advanced
# example. The bundle README + the repo quick start both point at the basic one (matching setup's
# own "copy config.json.template" guidance); the advanced example is "for more options".
# own "copy config.minimal.json" guidance); the advanced example is "for more options".
local out="$1" d="$WORKDIR/pithead"
mkdir -p "$d"
cp pithead VERSION docker-compose.yml config.json.template config.advanced.example.json "$d/" 2>/dev/null || true
cp pithead VERSION docker-compose.yml config.minimal.json config.reference.json "$d/" 2>/dev/null || true
local m
while IFS= read -r m; do
[ -e "$m" ] || {
Expand All @@ -482,7 +482,7 @@ make_bundle() {
mkdir -p "$d/$(dirname "$m")"
cp -R "$m" "$d/$(dirname "$m")/"
done < <(compose_build_mounts docker-compose.yml)
printf 'Pithead %s — pinned install bundle (images pulled from %s, no local build).\n\nQuick start:\n 1. cp config.json.template config.json # then set your Monero + Tari payout addresses\n (more options: config.advanced.example.json)\n 2. ./pithead setup\n\nThere are no build contexts here, so pithead pulls the published %s images instead of building.\n' \
printf 'Pithead %s — pinned install bundle (images pulled from %s, no local build).\n\nQuick start:\n 1. cp config.minimal.json config.json # then set your Monero + Tari payout addresses\n (more options: config.reference.json)\n 2. ./pithead setup\n\nThere are no build contexts here, so pithead pulls the published %s images instead of building.\n' \
"$TAG" "$REGISTRY" "$TAG" >"$d/README.txt"
if [ "$DRY_RUN" -eq 1 ]; then
printf ' %s[dry-run]%s would tar -> %s\n' "$C_YELLOW" "$C_RESET" "$out"
Expand Down
4 changes: 2 additions & 2 deletions tests/stack/run.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -813,7 +813,7 @@ BUILD_MOUNTS="$(
assert_contains "bundle ships monerod's config template" "$BUILD_MOUNTS" "./build/monero/bitmonero.conf.template"
assert_contains "bundle ships the tari config dir" "$BUILD_MOUNTS" "./build/tari"
# The bundle must ship the BASIC config template (the documented quick-start config — `cp
# config.json.template config.json`) and unpack to a versionless `pithead/` dir for the stable
# config.minimal.json config.json`) and unpack to a versionless `pithead/` dir for the stable
# /releases/latest/download/pithead.tar.gz URL. Build a real bundle and inspect it.
# shellcheck disable=SC1090,SC2034 # dynamic source; TAG/REGISTRY/DRY_RUN are consumed inside make_bundle
(
Expand All @@ -829,7 +829,7 @@ assert_contains "bundle ships the tari config dir" "$BUILD_MOUNTS" "./build/tari
make_bundle "$WORKDIR/pithead.tar.gz" >/dev/null 2>&1
tar tzf "$WORKDIR/pithead.tar.gz" 2>/dev/null
) >"$SANDBOX/bundle.list" 2>/dev/null
grep -q '^pithead/config.json.template$' "$SANDBOX/bundle.list" && ok "bundle ships config.json.template (basic quick-start config)" || bad "bundle ships config.json.template" "absent from the bundle"
grep -q '^pithead/config.minimal.json$' "$SANDBOX/bundle.list" && ok "bundle ships config.minimal.json (basic quick-start config)" || bad "bundle ships config.minimal.json" "absent from the bundle"
grep -q '^pithead/$' "$SANDBOX/bundle.list" && ok "bundle unpacks to versionless pithead/" || bad "bundle unpacks to pithead/" "top-level dir is not pithead/"
_bm_missing=""
for _m in $BUILD_MOUNTS; do [ -e "$ROOT/$_m" ] || _bm_missing="$_bm_missing $_m"; done
Expand Down