homelab/documentation/KBAs/KBA-002-SparkyFitness-Deployment.md

KBA-002: SparkyFitness — Initial Deployment on Heimdall

Status: Active
Created: May 10, 2026
Last Updated: May 10, 2026
Affected Systems: heimdall, Komodo, Traefik
Severity: Informational

---

Summary

Reference article for deploying SparkyFitness (self-hosted fitness tracker) on the heimdall node. Covers pre-deployment checklist, secret generation, first-boot sequence, and verification steps.

---

Use Case

You want to deploy SparkyFitness for the first time, or you are recovering from a failed deployment or data loss event and need to redeploy from scratch.

---

Prerequisites

Access Required

• SSH access to heimdall
• Gitea access: git.castaldifamily.com
• Komodo UI access: komodo.castaldifamily.com
• NFS share mounted and writable at /mnt/appdata/ on heimdall

Files in Repo

Confirm these files exist in nodes/heimdall/sparkyfitness/ on main:

• compose.yaml
• .env.example
• README.md

---

Resolution / Deployment Steps

Step 1 — Generate Secrets

On any machine with openssl available, generate the four required secrets:

# API encryption key — SAVE THIS. Do not rotate after data is stored.
openssl rand -hex 32

# Better Auth secret — SAVE THIS. Do not rotate after users enable 2FA.
openssl rand -hex 32

# Database superuser password
openssl rand -base64 24

# Application user password
openssl rand -base64 24

Store these immediately in the git-crypt-encrypted .env file at:

nodes/heimdall/sparkyfitness/.env

Using .env.example as the template:

cp nodes/heimdall/sparkyfitness/.env.example nodes/heimdall/sparkyfitness/.env
# Edit .env and fill in all four required secret values

⚠️ Confirm .gitattributes marks nodes/heimdall/sparkyfitness/.env as a git-crypt file before committing.

Step 2 — Create Appdata Directories

SSH into heimdall and pre-create the required directories:

ssh heimdall
mkdir -p /mnt/appdata/sparkyfitness/data/postgresql
mkdir -p /mnt/appdata/sparkyfitness/data/backup
mkdir -p /mnt/appdata/sparkyfitness/data/uploads

PostgreSQL will fail to initialize if postgresql/ does not exist or has incorrect ownership. Docker will create the directory automatically, but pre-creating it ensures the NFS mount is active and writable before the container starts.

Step 3 — Commit and Push

git add nodes/heimdall/sparkyfitness/
git commit -m "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 documented
- README covering access, appdata, backup scope

Source: https://github.com/CodeWithCJ/SparkyFitness"
git push origin main

Step 4 — Create Komodo Stack

1. Open Komodo UI → Stacks → New Stack
2. Configure:

Field	Value
Name	sparkyfitness
Server	heimdall
Source	Git Repo
Repo	homelab
Branch	main
Run Directory	nodes/heimdall/sparkyfitness
File Paths	(leave blank — uses compose.yaml by default)
Webhook	Enable — trigger on push to main
Auto Update	❌ Disabled

3. Click Deploy

Step 5 — First Boot Sequence

The startup order is enforced by depends_on + healthcheck conditions:

sparkyfitness-db (healthy) → sparkyfitness-server (healthy) → sparkyfitness-frontend

Expected timeline:

• sparkyfitness-db: healthy within ~30 seconds
• sparkyfitness-server: ~60–90 seconds (runs DB migrations on first boot)
• sparkyfitness-frontend: starts once server is healthy

Monitor startup:

ssh heimdall
docker compose -f /etc/komodo/stacks/sparkyfitness/compose.yaml logs -f

Step 6 — Set Admin Account

If SPARKY_FITNESS_ADMIN_EMAIL is set in .env, the first user with that email will be automatically granted admin on server startup.

Alternatively, register via the UI at https://fitness.castaldifamily.com, then promote from the Admin panel.

After creating your account, set SPARKY_FITNESS_DISABLE_SIGNUP=true in .env to close open registration. Redeploy to apply.

---

Verification

Run through the following checks after deployment:

Container Health

docker ps --filter "name=sparkyfitness"
# All three containers should show: Up X minutes (healthy)

Log Check

docker compose logs --tail=50 sparkyfitness-server
# Should show: server started, DB migrations complete, no ERRORs

UI Access

• Open https://fitness.castaldifamily.com in a browser
• Confirm: HTTPS with valid certificate, no browser errors
• Confirm: Login page loads

Traefik Routing

• Open Traefik dashboard → confirm sparkyfitness router is active and green
• Confirm TLS cert is issued via Cloudflare resolver

Restart Resilience

docker restart sparkyfitness-frontend
# Wait 30s, then confirm the UI is still accessible

---

Rollback

If deployment fails and you need to revert:

1. Stop the stack in Komodo: Stack → Stop
2. Remove containers: docker compose down on heimdall
3. The postgresql/ data directory is untouched by docker compose down (bind mount, not a volume)
4. Revert the compose file changes in Git and push — Komodo will redeploy the previous version

⚠️ docker compose down -v would only affect named volumes. Since we use bind mounts, data in /mnt/appdata/sparkyfitness/data/ is always preserved unless you manually delete it.

---

Related Resources

• SparkyFitness README
• Upstream GitHub
• Official Docs
• Docker Compose Install Guide
• Environment Variables Reference
• Postgres Upgrade Guide
• KBA-001: Komodo GitOps Stack Deployment Failures

---

Revision History

Date	Author	Change
2026-05-10	Nathan Castaldi	Initial deployment — SparkyFitness v0.16.6.1 on heimdall