nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/documentation/project-history/SESSION_SNAPSHOT_2026-05-10.md
Nathan 54a885120d feat(sparkyfitness): add sparkyfitness stack to heimdall 
- Compose file with pinned images (v0.16.6.1), healthchecks, Traefik routing
- .env.example with all required variables and generation commands
- README covering access, appdata, backup scope, upgrade procedure
- KBA-002: deployment reference with verification and rollback steps
- repo-deploy.prompt.md: reusable end-to-end deployment workflow prompt
- Session snapshot 2026-05-10

Source: https://github.com/CodeWithCJ/SparkyFitness
2026-05-10 21:58:38 -04:00

4.7 KiB
Raw Permalink Blame History

Session Snapshot - 2026-05-10

Summary

Built a reusable end-to-end repo deployment prompt (repo-deploy.prompt.md) and ran it live against SparkyFitness — a self-hosted fitness tracker. Completed all pre-deploy phases: repo analysis, classification, planning, compose authoring, and documentation. Stack is ready to deploy on heimdall pending live smoke tests on the node.

Work Completed

New Prompt

  • Created .github/prompts/repo-deploy.prompt.md — a gated, six-step workflow prompt that takes a repo URL and shepherds it through the full deployment lifecycle: analysis → classification → planning → compose authoring → documentation → testing → GitOps commit. Designed to be reusable for any future service.

SparkyFitness Deployment (heimdall)

  • Fetched and analyzed upstream repo (v0.16.6.1, 3.4k stars, actively maintained)
  • Classified as Category A (Docker Compose), Risk: Medium, Node: heimdall
  • Confirmed no port conflicts with existing heimdall services
  • Produced deployment plan: proxy-net + isolated sparkyfitness-network, no host ports exposed, Traefik routing to fitness.castaldifamily.com
  • Authored nodes/heimdall/sparkyfitness/compose.yaml with pinned images, healthchecks on all three services, resource limits, and Traefik labels
  • Authored nodes/heimdall/sparkyfitness/.env.example with all four required secrets, generation commands, and optional OIDC/SMTP/Garmin blocks
  • Created nodes/heimdall/sparkyfitness/README.md — full service reference (access, appdata, env vars, networking, backup/recovery, upgrade procedure, known issues)
  • Created documentation/KBAs/KBA-002-SparkyFitness-Deployment.md — step-by-step deployment KBA covering secret generation, appdata setup, Komodo stack creation, first-boot sequence, verification, and rollback

Files Changed

Action File
ADD .github/prompts/repo-deploy.prompt.md
ADD nodes/heimdall/sparkyfitness/compose.yaml
ADD nodes/heimdall/sparkyfitness/.env.example
ADD nodes/heimdall/sparkyfitness/README.md
ADD documentation/KBAs/KBA-002-SparkyFitness-Deployment.md

Validation and Test Results

Pre-Deploy Checks (static — all PASS)

  • ✅ All image tags pinned (postgres:18.3-alpine, sparkyfitness_server:v0.16.6.1, sparkyfitness:v0.16.6.1)
  • ✅ No secrets in tracked files — all four secrets use ${} interpolation; .env covered by .gitignore
  • ✅ No port conflicts on heimdall
  • ✅ Appdata pre-creation steps documented in KBA-002
  • ✅ .env.example documents all required variables with generation commands

Deploy / Post-Deploy Checks

  • ⬜ PENDING — require live execution on heimdall (Komodo stack creation, container health, Traefik routing, log check, restart resilience, webhook round-trip)

New Technical Debt

  • None. No @TODO or FIXME comments introduced this session.

Open Issues

  • SparkyFitness deploy/post-deploy smoke tests not yet run — stack has not been pushed to Komodo and brought live. Must complete before marking TESTS PASSED: sparkyfitness.
  • No git-crypt configured in this repo — .env files are excluded via .gitignore rather than encrypted and tracked. Secrets are not version-controlled. Recommend storing secrets in Vaultwarden and/or completing the git-crypt migration (see documentation/plans/plan-gitcryptMigration.md).
  • Garmin microservice (sparkyfitness-garmin) is commented out — upstream marks it as still in development. Revisit when maintainer marks stable.
  • Upcoming mandatory Postgres upgrade flagged by upstream in release notes — monitor and apply before it becomes breaking.

Next Steps

  1. SSH into heimdall, pre-create appdata directories (mkdir -p /mnt/appdata/sparkyfitness/data/{postgresql,backup,uploads})
  2. Generate secrets (openssl rand -hex 32 ×2, openssl rand -base64 24 ×2) and populate nodes/heimdall/sparkyfitness/.env
  3. Commit and push all new files to main
  4. Create Komodo stack sparkyfitness per KBA-002 Step 4
  5. Run live smoke test checklist from Step 5 and confirm TESTS PASSED: sparkyfitness
  6. Complete Gates 5 & 6 of repo-deploy.prompt.md (commit plan → deployment summary)
  7. After first use is stable, consider registering initial admin account and disabling open signup (SPARKY_FITNESS_DISABLE_SIGNUP=true)

Session Notes

  • repo-deploy.prompt.md was validated end-to-end in this session and is ready for reuse on future services. The gated confirmation model (exact phrases per step) worked well for keeping the workflow deliberate.
  • SparkyFitness chosen as the first service run through the new prompt. All static gates passed; live deploy is the remaining work.