hronicle

Chronicle your activity with automated Strava descriptions.

Chronicle your activity history through heatmaps.

Chronicle your workout sessions and send to garmin.

This app is a self-hosted Docker web app, Requires a Strava and Garmin account, and is compatible with Intervals.icu, SmashRun, WeatherAPI. Developed by a runner that wears a Garmin watch, other sports are untested and other brands are not supported.

Key Features

• Auto-processes new activities.
• Activity Profile matching,
  • yaml Profile Builder.
• Custom Description Templates per profile,
  • Jinja Template Builder
• Plan and wargame your next sessions.
  • yaml Workout Builder
  • Send to your garmin watch workout calendar.

Pages:

• View (/dashboard) for long-term trends.

• Plan (/plan) for planning your next move.

• Build (/editor) for template editing and preview.

• Sources (/setup) for source credentials and OAuth.

• Control (/control) for one-click API operations.

Quick Start

Step 0: Install Docker Desktop for Mac

1. Watch this quick setup video: https://www.youtube.com/watch?v=agkOZr27d3Y
2. Install Docker Desktop and launch it.

Step 1: Open Terminal

• Open Terminal.app.

Step 2: Create a folder and clone Chronicle Project

mkdir -p ~/docker/chronicle
cd ~/docker/chronicle
git clone https://github.com/seanap/Chronicle.git
cd Chronicle
cp .env.example .env

Step 3: Start Chronicle

docker compose up -d --build

• Re-run the same command after pulling new code so the latest backend and frontend assets are rebuilt into the image.

Step 4: Open the app

http://localhost:1609

Step 5: Add your credentials in Sources

• Go to Sources and fill in your source keys/tokens.
• Source setup guide: docs/SOURCES_SETUP.md

Using Chronicle

Auto-Descriptions:

• Go to Build page >
• Template Workshop Drawer >
  • Duplicate default Template, save-as, and load >
  • Modify Advanced Template jinja >
  • Confirm preview then Save + Publish
• Profile Workshop >
  • Select Profile from dropdown >
  • Enable >
  • Set Working
• Template Workshop >
  • Duplicate profile Template, save-as, and load >
  • Modify Advanced Template jinja >
  • Save + Publish

Plan

• Go to Plan page
  • Pace Workshop drawer >
    • Calcule Recent Race >
    • Set Marathon Goal
  • Type daily mileage targets >
    • Set run type to SOS to enable session workout >
    • select workout shorthand from dropdown, modify if needed
  • Workout Workshop drawer >
    • select template from dropdown >
    • modify yaml to customize, Save

View

• Go to View page >
  • Scope drawer >
    • Enable Years and Activity Types
  • Click the top Activity Type buttons to filter
  • Click the Data buttons to filter
  • Click the bottom Most Active buttons to filter

Documentation

• API docs: docs/API_DOCUMENTATION.md
• Android widget companion: docs/ANDROID_WIDGET_COMPANION.md
• Android widget APK downloads: GitHub Releases
• Misery Index report: docs/MISERY_INDEX_REPORT.md

Thanks!

Borrowed ideas, inspiration, code, and style from the following great projects:

• https://github.com/aspain/git-sweaty Dashboard inspiration
• https://github.com/yeekang-0311/garmin_planner Workout builder and Send to Garmin
• https://www.home-assistant.io/docs/configuration/templating/ Jinja Template builder inspired by HomeAssistant Templating
• https://activitystat.com/ For the auto stat description inspiration
• This project was built using the BMAD Method with assistance from CODEX GPT5.4