feat(miner-deployment): add fleet-mode gittensory-miner Docker image (#4295)

[andriypolanski]

Closes #4295

Summary

• Adds packages/gittensory-miner/Dockerfile — a two-stage fleet image built from the monorepo root with the same workspace COPY . . before npm ci ordering the root Dockerfile documents for @jsonbored/gittensory-engine.
• Runtime image runs as non-root node, defaults GITTENSORY_MINER_CONFIG_DIR=/data/miner, declares a /data/miner volume, and threads ARG GITTENSORY_VERSION → GITTENSORY_MINER_VERSION for fleet release tagging.
• Documents intentional no HEALTHCHECK in Dockerfile comments (CLI/batch workload, not a long-running HTTP service).
• Updates packages/gittensory-miner/DEPLOYMENT.md fleet walkthrough to docker build + docker run the new image instead of the ad hoc node:24-slim + npm install -g workaround.

Build / run

# From repo root
docker build -f packages/gittensory-miner/Dockerfile -t gittensory-miner:latest .

docker run --rm -it \
  -e GITTENSORY_MINER_CONFIG_DIR=/data/miner \
  -e GITHUB_TOKEN \
  -v miner-data:/data/miner \
  gittensory-miner:latest \
  doctor

Test plan

• test/unit/miner-deployment-doc.test.ts — DEPLOYMENT.md walkthrough strings + Dockerfile invariants
• docker build -f packages/gittensory-miner/Dockerfile . succeeds locally
• docker run … gittensory-miner:latest doctor exits 0 with mounted volume
• npm run test:ci green
• npm audit --audit-level=moderate clean

[superagent-security]

P2: npm prune runs lifecycle scripts of removed packages without --ignore-scripts

npm prune without --ignore-scripts can execute uninstall scripts of removed devDependencies during the build.

Add --ignore-scripts to npm prune to prevent lifecycle script execution during pruning.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name="packages/gittensory-miner/Dockerfile">
<violation number="1" location="packages/gittensory-miner/Dockerfile:23">
<priority>P2</priority>
<title>npm prune runs lifecycle scripts of removed packages without --ignore-scripts</title>
<evidence>RUN npm prune --omit=dev runs in the build stage and can execute preuninstall/uninstall/postuninstall scripts of packages being removed. A compromised devDependency could use these lifecycle hooks to execute malicious code or tamper with production files before they are copied to the runtime stage.</evidence>
<recommendation>Add --ignore-scripts to the npm prune --omit=dev command: RUN npm prune --omit=dev --ignore-scripts</recommendation>
</violation>
</file>

[superagent-security]

P2: npm prune runs lifecycle scripts of removed packages without --ignore-scripts

npm prune without --ignore-scripts can execute uninstall scripts of removed devDependencies during the build.

Add --ignore-scripts to npm prune to prevent lifecycle script execution during pruning.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name="packages/gittensory-miner/Dockerfile">
<violation number="1" location="packages/gittensory-miner/Dockerfile:23">
<priority>P2</priority>
<title>npm prune runs lifecycle scripts of removed packages without --ignore-scripts</title>
<evidence>RUN npm prune --omit=dev runs in the build stage and can execute preuninstall/uninstall/postuninstall scripts of packages being removed. A compromised devDependency could use these lifecycle hooks to execute malicious code or tamper with production files before they are copied to the runtime stage.</evidence>
<recommendation>Add --ignore-scripts to the npm prune --omit=dev command: RUN npm prune --omit=dev --ignore-scripts</recommendation>
</violation>
</file>

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 20:20:34 UTC}

3 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a two-stage fleet Dockerfile for gittensory-miner that mirrors the root gittensory-api Dockerfile's COPY-before-npm-ci workspace ordering, runs as non-root, and updates DEPLOYMENT.md + a doc-invariant test to match. The build/runtime split, ARG redeclaration for GITTENSORY_VERSION across stages, and USER node/mkdir ordering are all correct and traceable to the source layer they claim to fix. The main weakness is that unlike the root API image (which explicitly bundles into a single dist file to avoid shipping node_modules), this runtime stage copies the full pruned root node_modules plus the entire packages/gittensory-miner and packages/gittensory-engine source trees, pulling in hoisted deps and files unrelated to the miner CLI and materially increasing the image's attack surface.

Nits — 5 non-blocking

• packages/gittensory-miner/Dockerfile:24-26 copies the full pruned root node_modules (hoisted across the whole workspace) instead of bundling/scoping to just gittensory-miner + gittensory-engine deps the way the root gittensory-api Dockerfile does (which explicitly avoids this for a ~10× smaller, lower-surface image) — worth trimming or explaining why the miner doesn't follow that pattern, especially given this PR's Superagent security-review flag.
• packages/gittensory-miner/Dockerfile:25-26 copies the entire packages/gittensory-miner and packages/gittensory-engine directories (src, tests, tsconfig, etc.) into the runtime image rather than just dist + package.json, which is unnecessary bloat for a runtime-only stage.
• packages/gittensory-miner/Dockerfile:9 pins node:24-slim by tag only, not digest, so `docker build` isn't fully reproducible across time — low priority since it matches the existing root Dockerfile convention.
• CMD ["doctor"] as the default subcommand (packages/gittensory-miner/Dockerfile:38) is a reasonable default for `doctor` on first run but is easy to invoke unintentionally if an operator forgets to pass a subcommand — worth a one-line callout in DEPLOYMENT.md next to the entrypoint note that already exists.
• Consider following the root Dockerfile's bundling approach (scripts/build-selfhost.mjs-style) for gittensory-miner too, so the runtime image doesn't need node_modules at all — would shrink the image and narrow the dependency surface the Superagent scan is flagging.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4295
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 137 registered-repo PR(s), 82 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 137 PR(s), 25 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds packages/gittensory-miner/Dockerfile with the required non-root user, no baked secrets, GITTENSORY_MINER_CONFIG_DIR volume, and the COPY . . before npm ci workspace ordering fix mirrored from the root Dockerfile, and it updates DEPLOYMENT.md's fleet walkthrough plus test/unit/miner-deployment-doc.test.ts to keep the doc assertions green while adding new invariant checks. It also explic

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Rust, Cuda, Kotlin, MDX, Scala
• Official Gittensor activity: 137 PR(s), 25 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4307, issue #4295)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.01%. Comparing base (861e8b7) to head (ecd0bd2).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4462   +/-   ##
=======================================
  Coverage   94.01%   94.01%           
=======================================
  Files         418      418           
  Lines       37417    37417           
  Branches    13677    13677           
=======================================
  Hits        35178    35178           
  Misses       1583     1583           
  Partials      656      656           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.