SparkyFitness with Docker Compose

What SparkyFitness needs

Only figures SparkyFitness's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.

On top of this, Caddy (the reverse proxy in the file) is a single small container. SparkyFitness itself runs as 3 containers: sparkyfitness-db, sparkyfitness-server, sparkyfitness-frontend.

Which hardware SparkyFitness has images for

Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.

• x86-64 PC or NAS (linux/amd64): every image has a build.
• Raspberry Pi 4/5, 64-bit OS (linux/arm64): every image has a build.
• Raspberry Pi 3 or Zero 2 W, 32-bit OS (linux/arm/v7): no image for sparkyfitness-server, sparkyfitness-frontend. No image for this hardware; the builder leaves the app out.

A manifest says an image exists for a CPU, not how well SparkyFitness runs on it: a build for arm64 or arm/v7 can still be too slow or need more memory than the board has. The RAM and disk SparkyFitness publishes are in the table above and, for a whole set of apps against a Raspberry Pi, on Will it run on my machine?. A tag like latest can move to a new digest after the date checked.

docker-compose.yml

This is exactly what the builder writes for SparkyFitness alone on example.org: the official definition with its published ports removed and Caddy added in front. The time zone is Etc/UTC here; the builder uses your browser's. Every ${VARIABLE} is defined in the .env below.

# docker-compose.yml built at dankhost.com for: SparkyFitness
# Each app block is its official compose definition. Only the names were prefixed with
# the app slug (services, containers, volumes, bind folders, .env variables) so any set of
# apps can share one file; other differences are listed under "Changed:" in each block.
# Only Caddy publishes ports. Secrets live in .env next to this file.

services:
  # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ----
  # Source: https://caddyserver.com/docs/running (checked 2026-09-23)
  # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23)
  # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly.
  caddy:
    image: "caddy:2"
    container_name: "caddy"
    restart: "unless-stopped"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - "./caddy:/etc/caddy"
      - "caddy-data:/data"
      - "caddy-config:/config"
    networks:
      proxy:
        ipv4_address: "172.30.0.2"

  # ---- SparkyFitness (sparkyfitness.example.org) ----
  # Source: https://github.com/CodeWithCJ/SparkyFitness/blob/main/docker/docker-compose.prod.yml (checked 2026-10-09)
  # Source: https://codewithcj.github.io/SparkyFitness/install/docker-compose (checked 2026-10-09)
  # Source: https://codewithcj.github.io/SparkyFitness/install/environment-variables (checked 2026-10-09)
  # Source: https://codewithcj.github.io/SparkyFitness/administration/reverse-proxy (checked 2026-10-09)
  # Source: https://codewithcj.github.io/SparkyFitness/faq (checked 2026-10-09)
  # Source: https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore (checked 2026-10-09)
  # Changed: Removed the documented '${SPARKY_FITNESS_FRONTEND_PORT:-3004}:${NGINX_LISTEN_PORT:-80}' port and the database's container_name; Caddy reaches sparkyfitness-frontend:80 on the proxy network, and its nginx sends /api and /uploads on to the server.
  #          The four secrets the Docker Compose page says to replace are generated in .env: the two database passwords, SPARKY_FITNESS_API_ENCRYPTION_KEY as 64 hex digits (the length of its openssl rand -hex 32) and BETTER_AUTH_SECRET as 44 characters (the length of its openssl rand -base64 32). SPARKY_FITNESS_FRONTEND_URL is https://sparkyfitness.example.org, "the URL you will actually open the app at".
  #          The file's defaults are written in (database name, users, port 3010, log level, rate limit). The optional settings it passes through empty (email, OIDC, rate limits, outbound proxy, admin policy toggles) are left out: add the ones you use from the Environment Variables page.
  #          The healthcheck names the database and user directly instead of reading them from the container's variables.
  #          The file's own network, sparkyfitness-network, is the proxy network for the frontend and this app's network for the server and the database.
  sparkyfitness-db:
    image: "postgres:18.3-alpine"
    container_name: "sparkyfitness-db"
    restart: "always"
    environment:
      POSTGRES_DB: "sparkyfitness_db"
      POSTGRES_USER: "sparky"
      POSTGRES_PASSWORD: "${SPARKYFITNESS_SPARKY_FITNESS_DB_PASSWORD}"
      PUID: "1000"
      GUID: "1000"
    volumes:
      - "./sparkyfitness/postgresql:/var/lib/postgresql"
    healthcheck:
      test:
        - "CMD-SHELL"
        - "pg_isready -U sparky -d sparkyfitness_db"
      interval: "10s"
      timeout: "5s"
      retries: 10
      start_period: "30s"
    networks:
      sparkyfitness-backend: {}
  sparkyfitness-server:
    image: "codewithcj/sparkyfitness_server:latest"
    container_name: "sparkyfitness-server"
    restart: "always"
    environment:
      SPARKY_FITNESS_DB_HOST: "sparkyfitness-db"
      SPARKY_FITNESS_DB_PORT: "5432"
      SPARKY_FITNESS_DB_NAME: "sparkyfitness_db"
      SPARKY_FITNESS_DB_USER: "sparky"
      SPARKY_FITNESS_DB_PASSWORD: "${SPARKYFITNESS_SPARKY_FITNESS_DB_PASSWORD}"
      SPARKY_FITNESS_APP_DB_USER: "sparky_app"
      SPARKY_FITNESS_APP_DB_PASSWORD: "${SPARKYFITNESS_SPARKY_FITNESS_APP_DB_PASSWORD}"
      SPARKY_FITNESS_FRONTEND_URL: "https://sparkyfitness.example.org"
      SPARKY_FITNESS_API_ENCRYPTION_KEY: "${SPARKYFITNESS_SPARKY_FITNESS_API_ENCRYPTION_KEY}"
      BETTER_AUTH_SECRET: "${SPARKYFITNESS_BETTER_AUTH_SECRET}"
      NODE_ENV: "production"
      TZ: "Etc/UTC"
      SPARKY_FITNESS_LOG_LEVEL: "ERROR"
      SPARKY_FITNESS_SERVER_PORT: "3010"
      SPARKY_FITNESS_DISABLE_SIGNUP: "false"
      PUID: "1000"
      GUID: "1000"
    volumes:
      - "./sparkyfitness/backup:/app/SparkyFitnessServer/backup"
      - "./sparkyfitness/uploads:/app/SparkyFitnessServer/uploads"
    depends_on:
      sparkyfitness-db:
        condition: "service_healthy"
    networks:
      sparkyfitness-backend: {}
  sparkyfitness-frontend:
    image: "codewithcj/sparkyfitness:latest"
    container_name: "sparkyfitness-frontend"
    restart: "always"
    environment:
      SPARKY_FITNESS_FRONTEND_URL: "https://sparkyfitness.example.org"
      SPARKY_FITNESS_SERVER_HOST: "sparkyfitness-server"
      SPARKY_FITNESS_SERVER_PORT: "3010"
      NGINX_RATE_LIMIT: "5r/s"
      PUID: "1000"
      GUID: "1000"
    depends_on:
      - "sparkyfitness-server"
    networks:
      proxy: {}
      sparkyfitness-backend: {}

networks:
  # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact.
  # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's
  # ipv4_address and in every trusted-proxy value to a free 172.x.0 range.
  proxy:
    ipam:
      config:
        - subnet: "172.30.0.0/24"
          ip_range: "172.30.0.128/25"
          gateway: "172.30.0.1"
  sparkyfitness-backend: {}

volumes:
  caddy-data:
  caddy-config:

Caddyfile save as caddy/Caddyfile

Caddy gets and renews the HTTPS certificate for sparkyfitness.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.

# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.

# SparkyFitness
sparkyfitness.example.org {
	reverse_proxy sparkyfitness-frontend:80
}

Already running nginx, Nginx Proxy Manager, Caddy or Traefik? The reverse-proxy settings SparkyFitness needs, for all four, each cited to SparkyFitness's own docs.

.env

The secrets are left blank here on purpose: a password printed on a public page is the same for everyone who copies it. The builder fills them with random letters and digits made in your browser.

# .env for SparkyFitness, from dankhost.com/app/sparkyfitness/. Fill the blank secrets before starting.
# Keep this file private (chmod 600).

# SparkyFitness
# 32 random letters and digits: the builder fills this in your browser
SPARKYFITNESS_SPARKY_FITNESS_DB_PASSWORD=
# 32 random letters and digits: the builder fills this in your browser
SPARKYFITNESS_SPARKY_FITNESS_APP_DB_PASSWORD=
# 64 random letters and digits: the builder fills this in your browser
SPARKYFITNESS_SPARKY_FITNESS_API_ENCRYPTION_KEY=
# 44 random letters and digits: the builder fills this in your browser
SPARKYFITNESS_BETTER_AUTH_SECRET=

Changes from the official file

Besides prefixing every service, container, volume, folder and variable with sparkyfitness (so any set of apps can share one file), these are all the differences from what the project documents:

• Removed the documented '${SPARKY_FITNESS_FRONTEND_PORT:-3004}:${NGINX_LISTEN_PORT:-80}' port and the database's container_name; Caddy reaches sparkyfitness-frontend:80 on the proxy network, and its nginx sends /api and /uploads on to the server.
• The four secrets the Docker Compose page says to replace are generated in .env: the two database passwords, SPARKY_FITNESS_API_ENCRYPTION_KEY as 64 hex digits (the length of its openssl rand -hex 32) and BETTER_AUTH_SECRET as 44 characters (the length of its openssl rand -base64 32). SPARKY_FITNESS_FRONTEND_URL is https://sparkyfitness.example.org, "the URL you will actually open the app at".
• The file's defaults are written in (database name, users, port 3010, log level, rate limit). The optional settings it passes through empty (email, OIDC, rate limits, outbound proxy, admin policy toggles) are left out: add the ones you use from the Environment Variables page.
• The healthcheck names the database and user directly instead of reading them from the container's variables.
• The file's own network, sparkyfitness-network, is the proxy network for the frontend and this app's network for the server and the database.

Notes for SparkyFitness behind the proxy

• Open https://sparkyfitness.example.org and sign up: the first account to register becomes the admin (SPARKY_FITNESS_ADMIN_EMAIL is empty). Then turn sign-ups off with SPARKY_FITNESS_DISABLE_SIGNUP: "true" on the server and docker compose up -d, unless your family still has to join.
• Food lookups (OpenFoodFacts, and FatSecret or Nutritionix once you add keys under Food & Exercise Providers) and the AI features call outside services, so the server's network here has outgoing access.
• Without email settings there is no way to mail a password reset; add the SPARKY_FITNESS_EMAIL_* variables before you need one.
• The tags are latest; docker compose pull takes whatever is newest. The Garmin service, commented out in the file as work in progress, is not included.

Back it up

SparkyFitness makes its own scheduled backups: an archive of a database dump and the uploads folder, written to /app/SparkyFitnessServer/backup (./backup here). Its Manual Backup and Restore page says not to rely on them alone, so the plan also dumps the database itself.

Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.

# BACKUP.md built at dankhost.com for: SparkyFitness

What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.

The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.

Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.

## Before you start

    BACKUP=/mnt/backup/selfhost   # change this: a disk or machine other than this server's system disk
    mkdir -p "$BACKUP"

## Every time: the three stack files

    tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy

.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.

## Caddy (the reverse proxy)

Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.

- caddy-data (named volume, /data in caddy)
  BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
  SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
  IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.

Copy (Caddy keeps serving while you copy):

    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data

Restore check:

    tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
    docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"

Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)

## SparkyFitness

SparkyFitness makes its own scheduled backups: an archive of a database dump and the uploads folder, written to /app/SparkyFitnessServer/backup (./backup here). Its Manual Backup and Restore page says not to rely on them alone, so the plan also dumps the database itself.

What this compose mounts:
- ./sparkyfitness/postgresql (/var/lib/postgresql in sparkyfitness-db)
  COVERED BY THE COMMAND BELOW: PostgreSQL's data files: every account, diary entry, measurement and setting. The pg_dump below is the copy to keep.
- ./sparkyfitness/backup (/app/SparkyFitnessServer/backup in sparkyfitness-server)
  BACK UP: the app's own backup archives (sparkyfitness_full_backup_<date>.tar.gz), which its restore procedure reads.
- ./sparkyfitness/uploads (/app/SparkyFitnessServer/uploads in sparkyfitness-server)
  BACK UP: profile pictures and exercise images.

1. Database dump for sparkyfitness-db:

    docker compose exec -T sparkyfitness-db pg_dump -U sparky sparkyfitness_db > "$BACKUP/sparkyfitness-db.sql"

   PostgreSQL's own dump, run in this file's database service with the file's user and database name.

2. Copy (SparkyFitness keeps running):
   pg_dump gives a consistent copy while SparkyFitness runs; uploads are written once and not changed.

    tar czf "$BACKUP/sparkyfitness-backup.tar.gz" ./sparkyfitness/backup
    tar czf "$BACKUP/sparkyfitness-uploads.tar.gz" ./sparkyfitness/uploads

Restore check:

    grep -c 'PostgreSQL database dump complete' "$BACKUP/sparkyfitness-db.sql"   # 1 means pg_dump finished
    tar tzf "$BACKUP/sparkyfitness-backup.tar.gz" > /dev/null && echo OK
    tar tzf "$BACKUP/sparkyfitness-uploads.tar.gz" > /dev/null && echo OK

Put a copy back (with SparkyFitness stopped):

    tar xzf "$BACKUP/sparkyfitness-backup.tar.gz"   # recreates ./sparkyfitness/backup; move the old folder aside first
    tar xzf "$BACKUP/sparkyfitness-uploads.tar.gz"   # recreates ./sparkyfitness/uploads; move the old folder aside first

Into a fresh install, before the server starts against it:

    docker compose up -d sparkyfitness-db
    docker compose exec -T sparkyfitness-db psql -U sparky sparkyfitness_db < "$BACKUP/sparkyfitness-db.sql"

Put ./sparkyfitness/uploads back, keep the same SPARKY_FITNESS_API_ENCRYPTION_KEY and BETTER_AUTH_SECRET in .env (the FAQ: changing the secret signs everyone out), then:

    docker compose up -d

Sources:
- SparkyFitness docs: Manual Backup and Restore (in-app archives in /app/SparkyFitnessServer/backup): https://codewithcj.github.io/SparkyFitness/administration/manual_backup_restore (checked 2026-10-09)
- SparkyFitness docs: FAQ (locked out of MFA, temporary admin): https://codewithcj.github.io/SparkyFitness/faq (checked 2026-10-09)
- PostgreSQL docs: SQL Dump (pg_dump, restoring with psql): https://www.postgresql.org/docs/current/backup-dump.html (checked 2026-10-09)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-10-09)

Update it

What docker compose pull does depends only on how each image line in the compose file above is tagged. For SparkyFitness as this page writes it:

What SparkyFitness's docs say about updating

SparkyFitness' Docker Compose page starts and updates the stack the same way, from the folder holding the compose file:

docker compose pull && docker compose up -d

Source: SparkyFitness docs: Docker Compose (the secrets to replace, services, port 80) checked 2026-10-09

The steps

1. Back up first, as in Back it up above. An update can migrate SparkyFitness's data on its first start and its database with it; the copy is the way back.
2. Download the new images. Running containers are not touched yet:

   docker compose pull

3. Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:

   docker compose up -d

4. Watch SparkyFitness start (Ctrl+C stops following the log, not the app):

   docker compose logs -f sparkyfitness-frontend

5. Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:

   docker image prune

Docker's reference for these commands: Docker docs: docker compose pull checked 2026-09-30; Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30; Docker docs: docker image prune checked 2026-09-30

Locked out? Reset the admin password

SparkyFitness' docs give no command that resets a forgotten password; the reset they describe is by email.

1. Set up email before you need it: the Environment Variables page's email settings (SPARKY_FITNESS_EMAIL_HOST, _PORT, _SECURE, _USER, _PASS, _FROM) "Enable email delivery for password resets". This file leaves them out. Source: SparkyFitness docs: Environment Variables (frontend URL, admin email, sign-up, email) read 2026-10-09
2. If the only admin is locked out, the FAQ's route for a lost second factor gets an admin account back: sign up a new account (SPARKY_FITNESS_DISABLE_SIGNUP=false), set SPARKY_FITNESS_ADMIN_EMAIL to its address and restart, and the server promotes it on startup. Delete it when you are back in; removing the variable alone does not demote it. Source: SparkyFitness docs: FAQ (locked out of MFA, temporary admin) read 2026-10-09

Sources

Every page below was fetched on the date shown.

• SparkyFitness on GitHub (repository description) checked 2026-10-09 (what it does)
• SparkyFitness: docker/docker-compose.prod.yml (db, server, frontend) checked 2026-10-09 (compose definition and proxy settings)
• SparkyFitness docs: Docker Compose (the secrets to replace, services, port 80) checked 2026-10-09 (compose definition and proxy settings, update notes)
• SparkyFitness docs: Environment Variables (frontend URL, admin email, sign-up, email) checked 2026-10-09 (compose definition and proxy settings)
• SparkyFitness docs: Reverse Proxy (headers, frontend container on port 80) checked 2026-10-09 (compose definition and proxy settings)
• SparkyFitness docs: FAQ (locked out of MFA, temporary admin) checked 2026-10-09 (compose definition and proxy settings, backup plan)
• SparkyFitness docs: Manual Backup and Restore (in-app archives in /app/SparkyFitnessServer/backup) checked 2026-10-09 (compose definition and proxy settings, backup plan)
• Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
• Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
• PostgreSQL docs: SQL Dump (pg_dump, restoring with psql) checked 2026-10-09 (backup plan)
• Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-10-09 (backup plan)
• Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)
• PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30 (database upgrade)
• Docker docs: docker compose pull checked 2026-09-30 (update steps)
• Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30 (update steps)
• Docker docs: docker image prune checked 2026-09-30 (update steps)

Add SparkyFitness to the builder All one hundred apps