Skip to content

Add a systemd unit + timer example for running gittensory-miner continuously on a bare host (no Docker) #5197

Description

@JSONbored

Context

The repo already ships systemd/gittensory-docker-prune.service.example + .timer.example for ORB, but packages/gittensory-miner (AMS) has no equivalent for an operator who wants to run the CLI continuously on a bare host without Docker. DEPLOYMENT.md's fleet-mode framing today only covers Docker/docker-compose invocations.

Dependencies

None - independently shippable. Packaging/tooling template only; does not touch any runtime logic.

Requirements

  1. Before writing the unit file, determine whether AMS's discover/attempt/manage loop is meant to run as a persistent long-running process or as a periodic batch job - check the miner CLI's existing subcommands and any docs under packages/gittensory-miner for how the loop is invoked/orchestrated - and choose the systemd shape (service-only vs. service+timer) accordingly, stating the reasoning in the PR description.
  2. Add packages/gittensory-miner/systemd/gittensory-miner.service.example mirroring the existing ORB example's structure: User=, WorkingDirectory=, EnvironmentFile=, ExecStart= (pointing at the correct miner CLI invocation), and Restart=.
  3. If a periodic-invocation shape is the right fit, configure gittensory-miner.service.example as a oneshot service and also add gittensory-miner.timer.example (OnCalendar=/OnUnitActiveSec=), following the same conventions as the existing ORB timer example.
  4. Reference the appropriate existing env-file convention for the miner (or the .gittensory-miner.env.example starter file if that sibling candidate has already landed) in EnvironmentFile= - do not invent a new, undocumented env-file path.
  5. Add a short install/usage note (in the example file's comments or an adjacent README section) covering: copy to /etc/systemd/system/, drop the .example suffix, systemctl daemon-reload, systemctl enable --now.
  6. Do not add any Docker-based packaging in this PR - this is explicitly the bare-host, no-Docker alternative to the existing/planned docker-compose.miner.yml.

Deliverables / Acceptance Criteria

  • packages/gittensory-miner/systemd/gittensory-miner.service.example added, matching ORB's example structure
  • gittensory-miner.timer.example added if a periodic-invocation shape is chosen (with rationale documented in the PR)
  • Install/usage instructions included (inline comments or README section)
  • References an existing/documented env-file path, no new undocumented convention introduced
  • No Docker dependency added

Test Coverage Requirements

This PR must ship with full test coverage for every changed line and branch - the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Since this PR only adds static systemd unit-file templates under packages/gittensory-miner/systemd/ (no src/** code), the Codecov patch gate does not apply to the templates directly; instead: (1) manually verify each .service.example/.timer.example parses as valid systemd unit syntax (e.g. via systemd-analyze verify) and note the result in the PR description, (2) if any accompanying install-helper script is added, it must have full unit-test coverage of its success and failure paths (e.g. missing EnvironmentFile, invalid working directory) per the repo's 99%+ patch coverage gate, and (3) no regression test applies - this is net-new packaging, not a bug fix; state that explicitly in the PR description.

Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.

Expected Outcome

An operator without Docker can install a standard systemd unit (and timer, if periodic invocation is the right shape) to run gittensory-miner continuously or on a schedule on a bare host, matching the reliability conventions already established for ORB.

Links & Resources

  • systemd/gittensory-docker-prune.service.example / .timer.example (pattern reference)
  • packages/gittensory-miner/DEPLOYMENT.md
  • Theme: Self-host packaging & docs

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions