bincio-activity/README.md

BincioActivity

A federated, open-source, self-hosted activity stats platform. Own your data. Share what you want. Follow friends by URL.

What it is

BincioActivity turns a folder of GPX/FIT/TCX files into a beautiful, modern static website — no database, no server required. It can run from the local filesystem, GitHub Pages, or any static host.

Federation: anyone can "follow" a friend's data by adding a URL to their config. Friends' activities appear in your site, attributed to them.

Quick start

# Install
pip install bincio          # or: uv add bincio

# Extract your activities
cp extract_config.example.yaml extract_config.yaml
# edit extract_config.yaml with your paths
bincio extract

# Build the site (requires Node ≥ 20)
cd site && npm install
BINCIO_DATA_DIR=~/bincio_data npm run build
# open site/dist/index.html

Two stages

Stage 1 — Extract (bincio extract)

Reads GPX, FIT, TCX files (including .gz compressed) and writes a BincioActivity Schema (BAS) data store: plain JSON + GeoJSON files.

bincio extract                              # uses extract_config.yaml
bincio extract --input ~/rides --output ~/bincio_data
bincio extract --file ride.gpx             # single file → stdout
bincio extract --since 2025-01-01          # incremental

Supported sources:

• GPX (generic, Garmin extensions)
• FIT (Garmin, Hammerhead Karoo)
• TCX (including Garmin's https:// namespace variant)
• All of the above gzip-compressed (.gz)
• Strava bulk export (activities.csv carries titles and descriptions)

Stage 2 — Render (bincio render)

Generates a static site from the BAS data store using Astro.

cd site
BINCIO_DATA_DIR=~/bincio_data npm run dev    # development
BINCIO_DATA_DIR=~/bincio_data npm run build  # production build → site/dist/

Configuration

extract_config.yaml

owner:
  handle: yourname
  display_name: Your Name

input:
  dirs:
    - ~/Activities/gpx
    - ~/Activities/fit
  metadata_csv: ~/strava_export/activities.csv   # optional Strava metadata

output:
  dir: ~/bincio_data

default_privacy: public   # public | blur_start | no_gps | private

track:
  rdp_epsilon: 0.0001     # GPS simplification (~11m at equator)

incremental: true          # skip already-processed files

site/.env

BINCIO_DATA_DIR=/path/to/bincio_data

The BincioActivity Schema (BAS)

The data store is a directory of plain JSON files:

bincio_data/
  index.json               ← activity feed + owner manifest
  activities/
    {id}.json              ← full activity with timeseries
    {id}.geojson           ← simplified GPS track

See SCHEMA.md for the full specification. The schema is versioned and published as a standalone document so anyone can write importers in any language.

Federation

Add a friend's index.json URL to your site_config.yaml:

data_sources:
  - type: local
    path: ~/bincio_data
  - type: remote
    handle: alice
    url: https://alice.github.io/bincio/index.json

At build time the renderer fetches their public data and renders it under /friends/alice/.

Privacy

Privacy is enforced at the data layer — activities never leave your control:

Level	GPS track	Stats visible
public	Full track	Yes
blur_start	First/last 200 m removed	Yes
no_gps	Not published	Yes
private	Not published	Not in index

Tech stack

Layer	Technology
Extract	Python 3.12, click, fitdecode, gpxpy, lxml, rdp
Site framework	Astro (static generation)
UI components	Svelte 5
Styling	Tailwind CSS
Charts	Observable Plot
Maps	MapLibre GL + OpenFreeMap tiles
Package manager (Python)	uv
Package manager (Node)	npm

Development

# Python
uv sync
uv run pytest
uv run bincio --help

# Site
cd site && npm install
BINCIO_DATA_DIR=/tmp/bincio_test npm run dev