Davide Scaini
121 lines
3.1 KiB
Markdown
121 lines
3.1 KiB
Markdown
# 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
|
|
```
|
|
|
|
Set your handle and input directory at minimum:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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/`.
|
|
|
|
---
|
|
|
|
## Single-user — no login, static site
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
uv run bincio render --data-dir ~/bincio_data
|
|
# output: site/dist/
|
|
```
|
|
|
|
See [Single-user deployment](deployment/single-user.md).
|
|
|
|
---
|
|
|
|
## Multi-user — shared instance, login required
|
|
|
|
```bash
|
|
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](deployment/multi-user.md).
|
|
|
|
---
|
|
|
|
## Enable the edit UI (single-user)
|
|
|
|
The edit UI lets you rename activities, add descriptions, upload photos, and sync from Strava — from the browser.
|
|
|
|
```bash
|
|
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](deployment/single-user.md) — GitHub Pages, Netlify, VPS
|
|
- [Multi-user deployment](deployment/multi-user.md) — VPS with nginx, inviting users
|
|
- [CLI reference](reference/cli.md) — all commands and options
|
|
- [BAS schema](schema.md) — the data format and federation protocol
|