Hevy-Progress

Hevy-Progress

Docker app from Utgard21's Repository

Hevy My Progress is a colorful, self-hosted analytics dashboard for Hevy workout data.

Requirements

Optional Hevy API key for automatic workout and body-measurement sync. Workout CSV import and manual body measurements work without an API key.
Overview
Hevy My Progress is a colorful, self-hosted analytics dashboard for Hevy workout data. Track consistency, strength progression, training volume, muscle balance, recovery, personal records, monthly reports and your full workout calendar. Sync workouts and available body measurements through the Hevy API, or import workout CSV exports. The Measurements tab also supports manual entries and history charts. Includes workout history filters, quick date presets, pinned overview metrics, and clear sync status. Built primarily for my own training workflow and shared for others who may find it useful; your data, training style and preferences may differ, so some mappings, goals, analytics, defaults or settings may need adjustment. Unofficial project; not affiliated with or endorsed by Hevy.

Hevy My Progress

v1.0.0 · Available in Unraid Community Applications · Docker / Unraid · Self-hosted · MIT

A colorful, privacy-focused, self-hosted training analytics dashboard for Hevy, designed for Docker and Unraid.

Now available in Unraid Community Applications. Open Apps, search for Hevy Progress (existing catalog listing), and install it directly.

Unofficial project. Hevy My Progress is independent and is not affiliated with, endorsed by, or maintained by Hevy.

Built for my own training workflow. I originally built and configured Hevy My Progress around my own needs, workout data, training habits, and self-hosted setup. I am sharing it because it may be useful to others, but your Hevy data and preferences may be different. Some analytics, exercise/muscle mappings, defaults, goals, UI choices, or deployment settings may need to be adjusted for your own use. Please review the results rather than assuming every default is a perfect fit for your training.

For more detail on what may need customization, see docs/USAGE-NOTES.md.

What it does

Hevy My Progress turns your workout history into a private dashboard with:

  • Overview, Progress, Analytics, Muscles, Measurements, Calendar, and full-history Reports views
  • Workout history filters (routine, exercise, date), exercise search, quick date presets, pinned Overview statistics, and saved browser preferences
  • Separate last-sync-attempt and last-successful-sync timestamps, plus recorded/calculated/estimated data labels
  • Workout frequency, volume, sets, reps, duration, streaks, and lifetime totals
  • Exercise progression, rep PRs, estimated 1RM, PR timeline, and mini trend cards
  • Interactive front/back muscle heatmap, primary/secondary muscle contribution analytics, recovery view, and weekly muscle sets
  • Full-history training calendar and separated monthly reports with month-over-month comparisons, highlights, muscle distribution, and workout history
  • Automatic Hevy API sync or CSV import
  • Automatic import of available Hevy body measurements, plus manual measurements, history and trends
  • Persistent SQLite storage and JSON backup
  • Optional HTTP Basic Authentication
  • Multi-architecture Docker images for linux/amd64 and linux/arm64

For upgrades, troubleshooting, and measurement field details, see Unraid upgrade guide, FAQ and troubleshooting, measurement API notes, and changelog.

Demo & screenshots

A privacy-safe sample file is included at demo/demo-workouts.csv. Import it into a fresh/test instance to populate the dashboard for screenshots or to explore the UI without connecting a Hevy account.

Do not use demo data in your real instance unless you want those sample workouts stored alongside your own data.

Screenshots for the public listing should be captured from this demo dataset rather than a personal workout database. Screenshot maintenance: capture the current interface after each UI change, including Measurements and the latest sync indicators. Do not upload real measurements or identifiable workout history.

Unraid Community Applications

Hevy My Progress is available in the Unraid Community Applications catalog.

  1. Open the Apps tab in Unraid.
  2. Search for Hevy Progress (existing catalog listing).
  3. Select the app and install it.
  4. Add your Hevy API key if you want automatic API synchronization, or import a Hevy CSV export from the dashboard.

The native Unraid template is also included in this repository as hevy-progress.xml.

Unraid “Last Update” metadata

Hevy My Progress runs from GHCR (ghcr.io/utgard21/hevy-sync:latest). The current Community Applications client calculates the sidebar Last Update value for GHCR images by looking up a same-name repository on Docker Hub. If that Docker Hub mirror does not exist, Unraid can show Unknown even though the GHCR image and the Community Applications template are current.

This repository keeps GHCR as the canonical runtime registry. The GitHub Actions workflow also supports an optional Docker Hub metadata mirror. To enable it:

  1. Create a public Docker Hub repository named hevy-sync under the same Docker Hub username/namespace you want CA to query (for this project, utgard21/hevy-sync).
  2. Add GitHub Actions repository secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.
  3. Push to main or manually run the Docker workflow. It will continue publishing GHCR normally and will additionally publish <DOCKERHUB_USERNAME>/hevy-sync:latest.
  4. Refresh Community Applications after its metadata cache updates.

The XML <Date> field is still maintained for Community Applications metadata/changelog purposes, but it does not drive this sidebar value for a :latest Docker image.

Container image

Use the container image:

ghcr.io/utgard21/hevy-sync:latest

Map /data to a persistent appdata directory, expose container port 8080, and add the environment variables you need below.

The Hevy Public API is currently available to Hevy Pro users, and API keys are obtained from Hevy's developer settings. See the official Hevy API documentation.

Docker Compose

cp .env.example .env
# Edit .env and add your private values.
docker compose up -d --build

The included Compose file publishes the dashboard at port 8085.

Configuration

Variable Default Purpose
HEVY_API_KEY empty Optional Hevy API key
DATA_DIR /data Persistent database directory
TZ Europe/Sofia Workout dates and week boundaries
SYNC_INTERVAL 3600 Seconds between API syncs
DASHBOARD_USERNAME empty Optional HTTP Basic Auth username
DASHBOARD_PASSWORD empty Optional HTTP Basic Auth password

Set both dashboard username and password to enable authentication.

Security & privacy

The repository is safe to keep public only if secrets and personal workout data stay outside Git.

  • Never commit .env, your Hevy API key, dashboard password, SQLite database, CSV exports, or JSON backups.
  • The supplied .gitignore excludes common secret/config files and personal Hevy data.
  • Store persistent workout data only in the mapped /data directory.
  • If the dashboard is accessible outside your trusted LAN, put it behind HTTPS. Basic Auth does not encrypt credentials by itself.
  • Prefer a reverse proxy or private VPN for remote access rather than exposing port 8080 directly to the Internet.
  • If a secret was ever committed, removing it from the latest file is not enough: rotate the secret and remove it from Git history.

Body measurements

The Measurements tab automatically imports available body measurements during normal Hevy API synchronization. After updating your Unraid container, click Sync Hevy or wait for the next scheduled sync. The existing HEVY_API_KEY is used; no new environment variables or volume mappings are required. The imported fields depend on your Hevy account and API response.

You can still add measurements manually without an API key. Imported and manual measurements are stored separately in the persistent SQLite database in /data. For the same date and metric, the manual entry takes precedence in the dashboard without deleting the imported entry. Imported records are read-only in the dashboard: update them in Hevy and sync again. No body measurements are estimated from workouts.

If the import fails, inspect the sync status and verify API access. Preserve /data when updating or reinstalling the container; backups contain sensitive personal measurements.

Data handling

Hevy My Progress stores synced/imported workout data locally in SQLite under /data. The dashboard does not need your Hevy account password; API access uses HEVY_API_KEY.

Warm-up sets are excluded from working-set, rep, and volume totals. Muscle classification prefers Hevy exercise-template metadata when available and falls back to local mappings when necessary. Primary and secondary muscle contributions are clearly presented as inferred analytics; missing weight, reps, distance, or duration are never fabricated.

Authentication

Set:

DASHBOARD_USERNAME=your_username
DASHBOARD_PASSWORD=use-a-long-unique-password

If both are blank, authentication is disabled. If only one is configured, access is denied rather than silently running partially configured authentication.

Build & test

python -m unittest discover -s tests -v
node --check static/app.js
docker build -t hevy-dashboard:local .

Local run:

docker run -d \
  --name hevy-dashboard \
  -p 8085:8080 \
  -v /mnt/user/appdata/hevy-dashboard:/data \
  -e TZ=Europe/Sofia \
  hevy-dashboard:local

Upgrading on Unraid

Keep your existing /data appdata mapping, API key, timezone, and authentication settings. Back up the appdata folder (including hevy.sqlite) before pulling the latest image, then use Unraid's normal Update action and verify /health, workout history, and the Measurements tab. See the step-by-step Unraid upgrade guide.

Backup

Use the dashboard's Download data backup action or back up the persistent /data directory. Treat backups as private because they contain workout history.

Public-repository checklist

Before publishing a fork or sending a pull request:

  • Run git status and confirm no data/export files are staged.
  • Search the diff for API keys, passwords, email addresses, hostnames, and private URLs.
  • Use .env.example for variable names only; keep real values in .env.
  • Use redacted/demo data for screenshots and bug reports.
  • Rotate any credential that was accidentally pushed.

Hevy attribution

Workout data is obtained from Hevy through its public API or user-exported CSV files. Hevy and its branding belong to their respective owner. This project is an independent analytics dashboard.

Release

The first stable public release is v1.0.0. The container continues to publish latest, while version tags provide reproducible release images.

License

MIT License. See LICENSE.

Contributing

Issues and pull requests are welcome. Please do not attach personal workout exports, API keys, passwords, or unredacted database files to public issues.

Categories

Download Statistics

4,133
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/utgard21/hevy-sync:latest
Last Updated2026-10-23
First Seen2026-10-02

Runtime arguments

Web UI
http://[IP]:[PORT:8080]
Network
bridge
Shell
bash
Privileged
false

Template configuration

WebUIPorttcp

HTTP port for the Hevy My Progress dashboard.

Target
8080
Default
8080
AppdataPathrw

Persistent SQLite database and application data.

Target
/data
Default
/mnt/user/appdata/hevy-progress
Hevy API KeyVariable

Optional Hevy API key for automatic workout and available body-measurement synchronization. Leave blank for workout CSV import and manual body measurements.

Target
HEVY_API_KEY
Dashboard UsernameVariable

Optional dashboard username. Set both username and password to enable HTTP Basic Authentication.

Target
DASHBOARD_USERNAME
Dashboard PasswordVariable

Optional dashboard password. Use HTTPS if accessing the dashboard outside your trusted LAN.

Target
DASHBOARD_PASSWORD
TimezoneVariable

Timezone used for workout dates, calendar days and week boundaries.

Target
TZ
Default
Europe/Sofia
Sync IntervalVariable

Seconds between automatic Hevy API syncs. Minimum effective value is 300 seconds.

Target
SYNC_INTERVAL
Default
3600