running_page: a personal running site, and a README full of upgrade notes
Make your own running home page
At a glance
- What is it?
- running_page syncs activities from Strava, Nike, Garmin, Keep, Suunto and codoon into a SQLite file and renders them with a React and Vite front end. Its README opens with dated migration notes, which is honest and also the main thing a new fork has to read, from the Elevation Gain column added in 2024 to the Mapbox token warning.
- Who is it for?
- Use running_page if you already keep your training in one of the supported services and you want a static site that shows it, because the sync scripts, the SQLite store and the React front end are all in one template. Do not adopt it expecting a supported upgrade path, since the README's upgrade guidance is a list of dated notes rather than a migration guide, and check the accuracy caveat before you publish elevation numbers.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- yihong0618/running_page4,567 ★ · +39
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| yihong0618/running_page | 4.5k | 4.6k |
39 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The README is a changelog of dated migration notes
The most distinctive thing about this README is that it opens with upgrade notes rather than a description.
The first entries are operational housekeeping. Clone or fork before a Vercel 404, and pull the latest code. Python in the README means python3. If you use version 2.0, change the Vercel setting from gatsby to vite.
Then the notes become dated and specific. One is marked 2023.09.26 and concerns Garmin, where a `secret_string` is needed and has to be added in Actions as well. Another is marked 2024.09.29 and concerns the `Elevation Gain` field, with the exact error message a fork from before that update will hit.
That structure tells you what kind of project this is. It is a template that people fork, keep for years, and update by hand when the schema changes, and the README is the accumulated record of what that costs.
It is also the most useful part of the documentation for a new fork, because every entry corresponds to a decision a forker has to make rather than to a feature the template offers.
db_updater.py exists because SQLite will not migrate itself
The Elevation Gain note is the clearest worked example of the upgrade story.
If you forked before 2024.09.29, a sync fails with `sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such column: activities.elevation_gain`, and the fix is one script:
python run_page/db_updater.pyIf you have no local Python environment, there is a workaround that runs through CI. Set `RUN_TYPE` to `db_updater` in `.github/workflows/run_data_sync.yml` once, let the workflow run, then change it back.
Existing rows are a separate problem. To include `Elevation Gain` for past activities the note says to perform a full reimport, which means the upgrade costs a re-sync of your entire history rather than an incremental migration.
Whether the column is even displayed is a third switch: modify `SHOW_ELEVATION_GAIN` in `src/utils/const.ts`.
And the note closes with an accuracy warning, saying `Elevation Gain` may be inaccurate and pointing at Strava's Correct Elevation or Garmin's Elev Corrections features for more precise data. A template that tells you its own number is approximate is worth reading twice.
The Dockerfile dispatches on a single app argument
The container build is one shell script in a `Dockerfile`, and its logic is a chain of `if` and `elif` statements on one build argument.
The stages are two development images first. `develop-py` starts from `python:3.12-slim`, installs `requirements.txt`, and points pip at the Aliyun mirror with `pip3 config set global.index-url`. `develop-node` starts from `node:18`, sets the npmmirror registry, enables corepack and installs from `pnpm-lock.yaml`.
The `data` stage then inherits the Python image, takes build arguments for `app`, `nike_refresh_token`, `secret_string`, `client_id`, `client_secret`, `refresh_token`, `YOUR_NAME`, `keep_phone_number` and `keep_password`, and branches:
if [ "$app" = "NRC" ] ; then \
python3 run_page/nike_sync.py ${nike_refresh_token}; \
elif [ "$app" = "Garmin" ] ; then \
python3 run_page/garmin_sync.py ${secret_string} ; \
elif [ "$app" = "Garmin-CN" ] ; then \
python3 run_page/garmin_sync.py ${secret_string} --is-cn ; \
elif [ "$app" = "Strava" ] ; then \
python3 run_page/strava_sync.py ${client_id} ${client_secret} ${refresh_token};\
The chain continues with `Nike_to_Strava` and `Keep`, the latter called with `--with-gpx`, and anything else prints `Unknown app`.
Two things follow. Credentials arrive as build arguments rather than as environment variables, and the sync dispatch is a literal string comparison, so a typo produces a build that only prints `Unknown app`.
Six services write into one SQLite file
The data side of the template is a Python package, `run_page/`, containing one sync script per service.
The Dockerfile names `nike_sync.py`, `garmin_sync.py`, `strava_sync.py`, `nike_to_strava_sync.py` and `keep_sync.py`. The runners table in the README lists the services people actually run pages from, and the App column names Strava most often, then Nike, Garmin, Garmin-cn, Keep, Suunto and codoon.
The Garmin script takes a single `secret_string` argument, and the README shows how to obtain one:
python run_page/get_garmin_secret.py ${email} ${password}
# if cn
python run_page/get_garmin_secret.py ${email} ${password} --is-cnEverything lands in `run_page/data.db`, a SQLite file, and the sibling directories `GPX_OUT/`, `TCX_OUT/`, `FIT_OUT/` and `PNG_OUT/` hold derived artefacts. The `data:clean` script in `package.json` removes the database, the contents of those three OUT directories, `activities/*` and `src/static/activities.json`, which tells you the front end reads a generated JSON file rather than the database.
The dependency list explains the formats: `gpxpy`, `tcxreader`, `fit-tool` and `garmin-fit-sdk` parse GPX, TCX and FIT files, while `stravalib`, `garth` and `cloudscraper` handle the service APIs.
There is a terminal UI next to the web app
The Python package installs a console script, which is the first thing to notice in `pyproject.toml`:
[project.scripts]
run_page = "run_page.tui.app:main"So `running_page` is not only a web template. There is a terminal interface at `run_page/tui/app.py`, and the dependency list supports that reading: `textual` and `rich` are both present, which are the framework and the rendering library for a text user interface.
The root directory backs it up with test files named `test_tui.py` and `test_tui_app.py`, next to `test_generator.py` and `test_real.py`.
The Python side has its own strictness. `requires-python` is `>=3.12`, the build backend is `pdm-backend`, the package is declared as a distribution with `packages = ["run_page"]`, and the only development dependency is `pytest>=9.0.3`.
Platform handling is explicit too: `tzfpy` is required everywhere except Windows, where `timezonefinder` takes its place, and `eviltransform` in the Python dependencies pairs with `gcoord` in the front-end dependencies, both of which exist to convert coordinates for maps inside China.
Vercel or nginx, and MapCN instead of a shared Mapbox token
There are two deployment targets in the tree.
`vercel.json` is there, along with a `.vercelignore`, and the v2.0 note tells you to change the Vercel build setting from gatsby to vite, which tells you the front-end tool changed at the 2.0 release. `nginx.conf` is the other option, for self-hosting behind your own server.
The front end is React 19 with `react-router-dom`, built by Vite, with `mapbox-gl` and `react-map-gl` for the maps and `recharts` for the charts. Development is `pnpm run develop` or `pnpm run dev`, both of which run `vite dev`, and `pnpm run build` produces the bundle. `pnpm run ci` chains format, lint and build in that order.
The map note is the one with a warning attached. The project now uses MapCN, free, by default. If you choose Mapbox you have to get your own token, and the README says plainly not to use the maintainer's token, pointing at issue 643 and issue 1055.
That instruction is the difference between a template you can fork in an afternoon and one that leaves you relying on someone else's quota, so it is worth reading before anything else in the setup.
Three lock files, and two different version numbers
The repository carries three lock files for three toolchains: `pnpm-lock.yaml` for the front end, `pdm.lock` for the Python package, and `uv.lock` for a second Python workflow.
There are also three dependency manifests, `package.json`, `pyproject.toml` and `requirements.txt`, and the last of those duplicates the Python dependency list with slightly different pins. `cloudscraper` is pinned to 1.2.71 in `requirements.txt` while `pyproject.toml` leaves it unpinned, and `openai` is pinned to 1.88.0 in one and unpinned in the other.
Version numbers are similarly split. The Python package is at 2.5.1 in `pyproject.toml` while the npm package is at 1.0.0 in `package.json`, under the name `yihong.run` with the package manager pinned to `[email protected]`.
Release history matches the Python side: v2.5.1 was published on 2025-04-21 and v2.5 on 2025-04-19, with v2.0 from 2023-09-23 before that. The last push was on 2026-10-26, so commits continue well after the last tag.
What all of this adds up to is a template whose front-end version and Python version are numbered independently, which is fine for a solo-maintained fork and something to pin deliberately if you deploy it.
Editorial conclusion
Use running_page if you already keep your training in one of the supported services and you want a static site that shows it, because the sync scripts, the SQLite store and the React front end are all in one template. Do not adopt it expecting a supported upgrade path, since the README's upgrade guidance is a list of dated notes rather than a migration guide, and check the accuracy caveat before you publish elevation numbers. Before you fork, work through three things: whether your fork predates the `elevation_gain` column and therefore needs `run_page/db_updater.py`, which app your Dockerfile build should dispatch to through its `app` argument, and whether MapCN is acceptable for your maps or you need your own Mapbox token, since the README says not to use the maintainer's.
Frequently asked questions
What is yihong0618/running_page?
A MIT licensed template for a personal running home page. It syncs activities from services including Strava, Nike, Garmin, Garmin-CN, Keep, Suunto and codoon into a SQLite database at `run_page/data.db`, writes GPX, TCX and FIT output, and renders the result with a React and Vite front end. It also ships a terminal interface entry point, `run_page = "run_page.tui.app:main"`.
How do I get a Garmin secret_string for running_page?
Run `python run_page/get_garmin_secret.py ${email} ${password}`, adding `--is-cn` for the China variant. The README notes that the secret also has to be available in GitHub Actions. Its convention is that `python` in the documentation means `python3`.
Why does running_page fail with no such column: activities.elevation_gain?
The Elevation Gain field was added on 2024.09.29, so a fork from before that update needs the migration script `python run_page/db_updater.py`. Without a local environment, set `RUN_TYPE` to `db_updater` in `.github/workflows/run_data_sync.yml` once and change it back. Past activities need a full reimport, and `SHOW_ELEVATION_GAIN` in `src/utils/const.ts` controls whether the column is displayed.
Does running_page need a Mapbox token?
Not by default: the project now uses MapCN, which is free. If you choose Mapbox you must get your own token, and the README explicitly says not to use the maintainer's token, pointing readers at issue 643 and issue 1055.
How do I build and run the running_page front end?
With pnpm, which is pinned to `[email protected]`. `pnpm run develop` or `pnpm run dev` starts Vite, `pnpm run build` produces the production bundle, `pnpm run lint` runs eslint over `src`, and `pnpm run ci` runs format, lint and build in sequence. Deployment targets are a `vercel.json` for Vercel and `nginx.conf` for self-hosting.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yihong0618-running-page)Star history chart for your README
[](https://hysenlabs.com/projects/yihong0618-running-page)Was this useful?