Getting started

BincioActivity turns a folder of GPX/FIT/TCX files into a static website you host yourself. No database. No cloud dependency. No account.

Prerequisites

Python ≥ 3.12 and uv
Node ≥ 20 and npm (for the site)
Your activity files (Strava export, Garmin export, Karoo, etc.)

Install

git clone https://github.com/brutsalvadi/bincio-activity.git
cd bincio-activity
uv sync

Configure

cp extract_config.example.yaml extract_config.yaml
$EDITOR extract_config.yaml

Set your handle and input directory at minimum:

owner:
  handle: yourname          # used in URLs: /u/yourname/
  display_name: Your Name

input:
  dirs:
    - ~/your-activity-data/activities

output:
  dir: ~/bincio_data        # instance root; activities go into ~/bincio_data/yourname/

The config file is gitignored — safe to store Strava credentials here.

Extract

uv run bincio extract

Reads all GPX/FIT/TCX files and writes a BAS data store to ~/bincio_data/yourname/. Re-running is safe — unchanged files are skipped (hash-based).

--output overrides output.dir from the config and is the instance root, not the user directory. The handle is always appended automatically: bincio extract --output ~/bincio_data → writes to ~/bincio_data/yourname/.

# Build and preview
cd site && npm install && cd ..
uv run bincio dev --data-dir ~/bincio_data
# → http://localhost:4321

bincio dev merges edits, builds the shard manifest, and starts astro dev. No login required — the site opens directly at /u/yourname/.

To build for deployment (no live server):

uv run bincio render --data-dir ~/bincio_data
# output: site/dist/

See Single-user deployment.

uv sync --extra serve

# One-time: create the instance database and admin account
uv run bincio init --data-dir ~/bincio_data --handle yourname

# Start everything
uv run bincio dev --data-dir ~/bincio_data
# → http://localhost:4321  (login with the password set during init)

bincio dev detects the instance.db and automatically starts bincio serve alongside astro dev. Ctrl+C stops both.

See Multi-user deployment.

Enable the edit UI (single-user)

The edit UI lets you rename activities, add descriptions, upload photos, and sync from Strava — from the browser.

uv sync --extra edit
uv run bincio edit --data-dir ~/bincio_data
# Add to site/.env:
# PUBLIC_EDIT_URL=http://localhost:4041

In multi-user mode the edit UI is always available via bincio serve — no extra step needed.

Next steps

Single-user deployment — GitHub Pages, Netlify, VPS
Multi-user deployment — VPS with nginx, inviting users
CLI reference — all commands and options
BAS schema — the data format and federation protocol

3.1 KiB Raw Blame History