# 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](https://docs.astral.sh/uv/)
- Node ≥ 20 and npm (for the site)
- Your activity files (Strava export, Garmin export, Karoo, etc.)

## Install

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

## Configure

```bash
cp extract_config.example.yaml extract_config.yaml
$EDITOR extract_config.yaml
```

Minimum configuration:

```yaml
owner:
  handle: yourname       # used in URLs and federation
  display_name: Your Name

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

output:
  dir: ~/bincio_data
```

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

## Extract

```bash
uv run bincio extract
```

This reads all GPX/FIT/TCX files (including `.gz` variants), deduplicates them, and writes a BAS data store to `~/bincio_data/`.

Re-running is safe — unchanged files are skipped (hash-based). To force a full re-extract: `rm -rf ~/bincio_data && uv run bincio extract`.

## Build the site

```bash
cd site && npm install && cd ..
cp site/.env.example site/.env
# Edit site/.env: set BINCIO_DATA_DIR=~/bincio_data
uv run bincio render
```

Output is in `site/dist/` — a folder of static files. Drop it anywhere: GitHub Pages, Netlify, a Raspberry Pi, a USB stick.

## Dev mode

```bash
uv run bincio render --serve    # → http://localhost:4321
```

## Enable the edit UI

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

```bash
uv sync --extra edit
uv run bincio edit              # starts on http://localhost:4041
# Add to site/.env:
# PUBLIC_EDIT_URL=http://localhost:4041
```

An Edit button and an Upload ↑ button appear in the nav.

## Next steps

- [Single-user deployment](deployment/single-user.md) — serve your site on a VPS or GitHub Pages
- [Multi-user deployment](deployment/multi-user.md) — invite friends, shared feed
- [CLI reference](reference/cli.md) — all commands and options
- [BAS schema](../SCHEMA.md) — the data format and federation protocol