# Project pack: Endurain @ 2f33e45

Facts about **Endurain** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Endurain keeps a diary of your exercise on your own server. Upload files from your watch or bike computer, or link Garmin Connect or Strava, and see each run, ride or swim with its map, pace and heart rate. A health section tracks sleep, weight, steps, water and more, and you can set weekly goals. Friends can follow you, but everything is private unless you choose to share it.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. A bare-metal install is documented but also needs a domain and an HTTPS reverse proxy. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://docs.endurain.com
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/endurain-project/endurain
- Pinned commit: `2f33e455989278a9c64d50d1994aab63b204ecf2`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/endurain-project/endurain/archive/2f33e455989278a9c64d50d1994aab63b204ecf2.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.endurain.com
- Live demo: https://demo.endurain.com (username: admin / password: admin). Official shared demo. It resets every night (Lisbon time). Don't upload anything private.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. "Endurain" is a trademark: self-hosting and non-commercial use of the name are fine, but paid hosting under that name needs the author's permission.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/endurain-project/endurain bespoke-endurain
  cd bespoke-endurain
  git checkout --detach 2f33e455989278a9c64d50d1994aab63b204ecf2
  # Prepare development requirements and local configuration first.
  # Setup notes: backend + Postgres, see docs/developer-guide/setup-dev-env.md; then cd frontend && npm install && npm run dev
  docker build -f docker/Dockerfile -t unified-image . && docker compose up -d
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  sudo mkdir -p /var/opt/endurain/backend/{data,logs}
  sudo chown -R 1000:1000 /var/opt/endurain/backend
  cd /var/opt/endurain
  wget -O docker-compose.yml https://raw.githubusercontent.com/endurain-project/endurain/master/docker-compose.yml.example
  wget -O .env https://raw.githubusercontent.com/endurain-project/endurain/master/.env.example
  # edit .env: DB_PASSWORD = POSTGRES_PASSWORD (openssl rand -hex 32), SECRET_KEY (openssl rand -hex 32),
  # FERNET_KEY (openssl rand -base64 32), TZ and ENDURAIN_HOST (your https address)
  sudo docker compose up -d
  # serve it over HTTPS with a reverse proxy, log in as admin/admin and change the password at once
  ```
- Tools these commands use: Docker with Docker Compose, A domain and HTTPS reverse proxy (Caddy, Nginx Proxy Manager…). Login cookies are HTTPS-only in production., For development, Python 3.13 with uv, and Node.js 24 (or 22.18+)
- Develop: `docker build -f docker/Dockerfile -t unified-image . && docker compose up -d   # backend + Postgres, see docs/developer-guide/setup-dev-env.md; then cd frontend && npm install && npm run dev`
- Test: `cd backend && uv sync && uv run pytest -q && cd ../frontend && npm test`
- Check/lint: `cd backend && PYTHONPATH=app uv run lint-imports && uv run ruff format --check . && uv run ruff check . && cd ../frontend && npm run check`
- Stack: python, typescript, vue (FastAPI, SQLAlchemy 2, Alembic, Vue 3, Vite, Tailwind CSS 4, shadcn-vue, TanStack Query, Pinia). Difficulty for a non-developer with an AI: **advanced**. A substantial two-part app: a FastAPI backend split into strict modules (backend/app/modules/) with import rules enforced by tests, and a Vue 3 TypeScript frontend organised by feature (frontend/src/features/). The frontend's API types are generated from the backend. Upstream's AGENTS.md and skills are thorough, which helps an AI a lot, but most changes touch both halves.
- The project's own AI instructions, in the repository: `AGENTS.md`, `.agents/skills/endurain-backend/SKILL.md`, `.agents/skills/endurain-frontend/SKILL.md`, `CONTRIBUTING.md`.
Personal data: **yes**. Stored in: PostgreSQL (LOCAL_PATH/postgres) for activities, health data and users; original activity files and photos in LOCAL_PATH/backend/data. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/endurain/2f33e45/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/endurain/2f33e45/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/endurain/2f33e45/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/endurain/2f33e45/r3/SKILL.md)