Davide Scaini
163 lines
3.9 KiB
Markdown
163 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
# Python
|
|
uv sync
|
|
uv run pytest
|
|
uv run bincio --help
|
|
|
|
# Site
|
|
cd site && npm install
|
|
BINCIO_DATA_DIR=/tmp/bincio_test npm run dev
|
|
```
|