Skip to content

armgit / lyftr

Public Imported from GitHub
0

Self-hosted fitness tracker. Log workouts, track nutrition, and monitor progress. Docker deployment, mobile-friendly.

docs: simplify README + expand & correctness-fix the docs site (#71)

Carter82f4a60db1e2
diff --git a/README.md b/README.md
index 4a9884c..2a15c7b 100644
--- a/README.md
+++ b/README.md
@@ -1,247 +1,99 @@
<p align="center">
- <a href="https://github.com/Cawlumm/lyftr/releases?q=v0"><img src="https://img.shields.io/github/v/release/Cawlumm/lyftr?filter=v*&label=release&color=6366f1" alt="Latest release" /></a>
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
- <img src="https://img.shields.io/badge/status-beta-orange" alt="Beta" />
- <a href="https://selfh.st/weekly/2026-04-24/"><img src="https://img.shields.io/badge/Featured%20in-selfh.st%20%C2%B7%20Apr%202026-6366f1" alt="Featured in selfh.st" /></a>
- <a href="https://github.com/Cawlumm/lyftr/releases?q=mobile-v"><img src="https://img.shields.io/github/v/release/Cawlumm/lyftr?filter=mobile-v*&label=Android&logo=android&logoColor=white&color=3ddc84" alt="Android APK" /></a>
- <img src="https://img.shields.io/badge/iOS-planned-black?logo=apple&logoColor=white" alt="iOS Planned" />
- <a href="https://discord.gg/hfFWsrebQA"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Join Discord" /></a>
+ <img src="docs/banner.png" alt="Lyftr — self-hosted workout tracking" width="100%" />
</p>
<p align="center">
- <img src="docs/banner.png" alt="Lyftr — Self-hosted workout tracking" width="100%" />
+ <b>Self-hosted, mobile-first workout &amp; nutrition tracker.</b><br />
+ Free, open source, and yours to run — own your data.
</p>
-> 📱 **The Lyftr Android app is live — [download the APK](https://github.com/Cawlumm/lyftr/releases/download/mobile-v0.1.0/lyftr-mobile-v0.1.0.apk)** and track your workouts on your phone. This is an early beta — more polish, auto-updating store builds, and an iOS version are on the way.
-
-> 🎉 **First beta release is live — [`v0.1.0-beta.1`](https://github.com/Cawlumm/lyftr/releases/tag/v0.1.0-beta.1).** Workouts, programs, gym mode, dashboard, weight, and the new nutrition tracker are all in. Pin this tag for a stable self-host target instead of tracking `main`.
-
-> **Beta** — actively being built. Expect rough edges and frequent updates. Issues and feedback are welcome. The software equivalent of going to the gym for the first time.
-
-> 🌐 **[Live demo → lyftr-demo.fly.dev](https://lyftr-demo.fly.dev)** — log in with `[email protected]` / `password123`. Shared instance, resets every hour.
-
----
-
-## 📱 Get the app
-
-<a href="https://github.com/Cawlumm/lyftr/releases?q=mobile-v"><img src="https://img.shields.io/github/v/release/Cawlumm/lyftr?filter=mobile-v*&label=Download%20Android%20APK&logo=android&logoColor=white&color=3ddc84" alt="Download Android APK" /></a>
-
-**Android** — download the latest signed APK from the [Releases](https://github.com/Cawlumm/lyftr/releases?q=mobile-v) page, or grab the current build directly:
-
-**[⬇️ Download the Android APK](https://github.com/Cawlumm/lyftr/releases/download/mobile-v0.1.0/lyftr-mobile-v0.1.0.apk)** (`mobile-v0.1.0`, ~102 MB)
-
-1. Open the `.apk` on your Android phone.
-2. Allow **"install from unknown sources"** if prompted.
-3. Launch Lyftr and point it at your server.
-
-> Side-loaded builds don't auto-update — when a new `mobile-v*` release drops, download and install it over the old one.
-
-**iOS** — planned. Apple doesn't allow side-loading, so iOS will ship via **TestFlight** / the App Store once the Apple Developer account is set up.
-
----
-
-## Runs on
-
-Tested and working on:
-
-- **Raspberry Pi 4** (2 GB RAM, arm64 Docker image)
-- **Any x86 VPS** — Hetzner CAX11, DigitalOcean Droplet, Oracle Free Tier
-- **Synology NAS** via Docker (Container Manager)
-- **Proxmox LXC** with Docker installed
-- **Local machine** — Mac, Linux, Windows (WSL2)
-
-Single SQLite file, minimal RAM, no external services required.
-
----
-
-## Why Lyftr?
-
-**Hevy and Strong** are polished apps but cloud-only, increasingly paywalled, and your data lives on someone else's server. **Wger** is a solid self-hosted option with a lot of features — Lyftr's focus is a more modern, mobile-first UI and a simpler deployment story. **FitNotes** is local-only with no sync or server deployment story.
-
-Lyftr is for people who want a modern, mobile-first workout tracker that they fully own and can run on a $5 VPS or a Raspberry Pi in the corner. No subscription. No vendor lock-in. No "your export is a Pro feature."
-
----
-
-## Features
-
-| Feature | Status |
-|---------|--------|
-| Workout logging with 800+ exercise library | ✓ |
-| Program builder — reusable workout templates | ✓ |
-| Active workout mode — guided set-by-set flow | ✓ |
-| Gym Mode — full-screen card layout, one exercise at a time | ✓ |
-| Exercise detail — personal records, progression chart, muscle diagram | ✓ |
-| Dashboard — volume trends, consistency heatmap, muscle balance | ✓ |
-| Weight tracking with trend graph | ✓ |
-| lbs / kg unit support across all data | ✓ |
-| Self-hosted — all data stays on your server | ✓ |
-| Nutrition tracking — calories, macros, barcode scan, food search | ✓ |
-| PWA — installable on any device | Planned |
-| Strong / Hevy CSV import | Planned |
-| iOS app (Swift) | Planned |
-
----
-
-## Live Demo
-
-**[lyftr-demo.fly.dev](https://lyftr-demo.fly.dev)**
-
-| Field | Value |
-|-------|-------|
-| Email | `[email protected]` |
-| Password | `password123` |
-
-Pre-loaded with 8 weeks of PPL workouts, 90 days of weight logs, and food logs so every page has data to explore. Shared instance — resets automatically every hour so any changes are wiped clean.
-
-Or **register your own account** on the demo — your data persists until the next hourly reset, and nobody else can see it.
-
----
-
-## Quick Start
-
-> No clone. No build. No Go install required. Just Docker.
-
-```bash
-curl -o docker-compose.yml https://raw.githubusercontent.com/Cawlumm/lyftr/main/docker-compose.yml
-curl -o .env https://raw.githubusercontent.com/Cawlumm/lyftr/main/.env.example
-```
-
-Edit `.env` and set a strong `JWT_SECRET` (32+ characters), then:
-
-```bash
-docker compose up -d
-```
-
-Open `http://localhost` in your browser and create your account. If running on a VPS, replace `localhost` with your server IP or domain.
-
----
-
-## More Screenshots
-
<p align="center">
- <img src="docs/screenshots/workouts-mobile.png" width="160" alt="Workouts" />
- <img src="docs/screenshots/active-workout-mobile.png" width="160" alt="Active Workout" />
- <img src="docs/screenshots/gym-mode-overview-mobile.png" width="160" alt="Gym Mode Overview" />
- <img src="docs/screenshots/programs-mobile.png" width="160" alt="Programs" />
- <img src="docs/screenshots/settings-mobile.png" width="160" alt="Settings" />
+ <a href="https://lyftr-demo.fly.dev">Live demo</a> ·
+ <a href="https://lyftr-app.pages.dev">Docs</a> ·
+ <a href="https://github.com/Cawlumm/lyftr/releases?q=mobile-v">Download APK</a> ·
+ <a href="https://discord.gg/hfFWsrebQA">Discord</a>
</p>
<p align="center">
- <img src="docs/screenshots/gym-mode-overview-desktop.png" width="700" alt="Gym Mode desktop" />
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+ <img src="https://img.shields.io/badge/status-beta-orange" alt="Beta" />
+ <a href="https://selfh.st/weekly/2026-04-24/"><img src="https://img.shields.io/badge/Featured%20in-selfh.st-6366f1" alt="Featured in selfh.st" /></a>
+ <a href="https://github.com/Cawlumm/lyftr/releases?q=mobile-v"><img src="https://img.shields.io/github/v/release/Cawlumm/lyftr?filter=mobile-v*&label=Android&logo=android&logoColor=white&color=3ddc84" alt="Android APK" /></a>
+ <img src="https://img.shields.io/badge/iOS-planned-black?logo=apple&logoColor=white" alt="iOS planned" />
</p>
---
-## Configuration
-
-All variables live in `.env` at the project root.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `JWT_SECRET` | *required* | Min 32-char secret for signing tokens |
-| `CORS_ORIGIN` | `http://localhost` | Comma-separated allow-list of client origins. Use `*` to allow any (the API is Bearer-token based, no cookies) |
-| `PORT` | `80` | Host port for the web interface |
-| `BACKEND_ORIGIN` | `backend:3000` | Docker **service name**:port the frontend proxies `/api` to — not a host IP. Only change the port, to match a custom backend `PORT` |
-
-> **Self-hosting note:** `BACKEND_ORIGIN` is resolved over the internal Docker network, so it must use the backend's **service name** (`backend`), not your server's host or LAN IP. The default compose only *exposes* the backend on the Docker network — it isn't published to the host — so pointing `BACKEND_ORIGIN` at something like `192.168.1.10:3000` produces a `502 Bad Gateway` (`connect() failed (111: Connection refused)`). If you set a custom backend `PORT`, change only the port (e.g. `backend:3008`).
-
----
-
-## Exercise Library
-
-On first startup, Lyftr automatically seeds 800+ exercises from [free-exercise-db](https://github.com/yuhonas/free-exercise-db) in the background. No API key. No setup required. It just works.
+## What is Lyftr?
-```
-[startup] exercises table empty — fetching from free-exercise-db...
-[startup] seed: synced 868 exercises
-```
-
-The seed runs async so the server is immediately available. Exercises appear in the UI within a few seconds.
-
-**Re-sync exercises:** Go to **Settings → Exercise Library** — shows current exercise count and a progress indicator while seeding. Hit **Re-sync** to pull the latest exercises (safe upsert, existing workout data is untouched).
-
----
+A workout tracker you fully own. Log workouts, build reusable programs, run a guided gym session with
+a rest timer, and track nutrition and bodyweight — all self-hosted and lightweight, with your data in
+a single SQLite file on your server.
-## Data & Backups
+No subscription. No lock-in. No "your export is a Pro feature."
-All workout data is stored in `./data/lyftr.db` (SQLite). Back this up regularly. It's one file. You have no excuse.
+## Features
-```bash
-# Backup
-cp ./data/lyftr.db ./data/lyftr.db.backup
+| | |
+|---|---|
+| 🏋️ **Workouts** | 800+ exercise library, program builder, guided active mode |
+| 📱 **Gym Mode** | Full-screen, one exercise at a time, with a rest timer |
+| 📈 **Progress** | Personal records, progression charts, muscle diagrams, dashboard |
+| 🍎 **Nutrition** | Calories, macros, barcode scan, food search |
+| ⚖️ **Weight** | Trend graph, lbs / kg across all data |
+| 🔒 **Yours** | Self-hosted — a single SQLite file, all data on your server |
-# Update to latest
-docker compose pull && docker compose up -d
-```
+_Planned: PWA · Strong/Hevy CSV import · iOS app._
----
+<p align="center">
+ <img src="docs/screenshots/workouts-mobile.png" width="150" alt="Workouts" />
+ <img src="docs/screenshots/active-workout-mobile.png" width="150" alt="Active workout" />
+ <img src="docs/screenshots/gym-mode-overview-mobile.png" width="150" alt="Gym Mode" />
+ <img src="docs/screenshots/programs-mobile.png" width="150" alt="Programs" />
+ <img src="docs/screenshots/settings-mobile.png" width="150" alt="Settings" />
+</p>
-## Running on a VPS
+## Quick start
-> Because paying $15/month for a fitness app subscription is money better spent on protein powder.
+No clone, no build — just Docker:
```bash
-sudo apt update && sudo apt install -y docker.io docker-compose-plugin
-
-mkdir lyftr && cd lyftr
curl -o docker-compose.yml https://raw.githubusercontent.com/Cawlumm/lyftr/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/Cawlumm/lyftr/main/.env.example
-nano .env # set JWT_SECRET and CORS_ORIGIN
-
-docker compose up -d
+# set a strong JWT_SECRET in .env, then pull the prebuilt images and start:
+docker compose pull && docker compose up -d
```
-For HTTPS, put Lyftr behind Caddy or nginx with a Let's Encrypt certificate.
-
----
-
-## Roadmap
-
-- [x] Workout logging + program builder
-- [x] Active workout mode (list + gym mode layouts)
-- [x] Exercise detail — PRs, progression chart, muscle diagram
-- [x] Dashboard with charts and trends
-- [x] Weight tracking with trend graph + lbs/kg support
-- [x] Docker deployment with E2E test pipeline
-- [x] Nutrition tracking — calories, macros, Open Food Facts search, barcode scan, history
-- [ ] PWA — installable on any device without an app store
-- [ ] Strong / Hevy CSV import — so you don't lose years of data switching
-- [ ] Apple Health / Google Fit export
-- [ ] iOS app (Swift)
-- [ ] Hosted option (no self-hosting required)
-
----
-
-## Tech Stack
+Open `http://localhost` and create your account.
-| Layer | Technology |
-|-------|-----------|
-| Backend | Go, Gin, SQLite |
-| Frontend | React, TypeScript, Tailwind CSS, Vite |
-| Auth | JWT with refresh tokens |
-| Deployment | Docker, nginx |
+📖 **Full guide** — configuration, HTTPS, backups, the mobile app, and troubleshooting live in the
+**[docs → lyftr-app.pages.dev](https://lyftr-app.pages.dev)**.
----
+## Try it
-## Development
+- **Live demo** — [lyftr-demo.fly.dev](https://lyftr-demo.fly.dev) · `[email protected]` / `password123` (resets hourly)
+- **Android** — [download the APK](https://github.com/Cawlumm/lyftr/releases?q=mobile-v), then point it at your server ([mobile docs](https://lyftr-app.pages.dev/mobile/)). iOS is planned.
-```bash
-# Backend (runs on :3000)
-cd backend && go run main.go
+## Roadmap
-# Frontend (runs on :5173, proxies /api to :3000)
-cd web && npm install && npm run dev
-```
+- [x] Workouts, programs, gym mode, rest timer
+- [x] Exercise PRs, progression charts, dashboard
+- [x] Weight + nutrition tracking
+- [x] Docker deploy · Android app · docs site
+- [ ] PWA · Strong/Hevy CSV import · iOS app · hosted option
-See `backend/config/config.go` for all supported environment variables.
+## Tech stack
----
+Go · Gin · SQLite — React · TypeScript · Tailwind · Vite (web) — React Native · Expo (mobile) —
+Astro · Starlight (docs) — Docker · nginx.
## Contributing
-Bug reports, feature requests, and pull requests are all welcome. Open an issue before submitting large changes — unlike leg day, communication should not be skipped.
+Bug reports, feature requests, and PRs are welcome — open an issue before large changes. Development
+setup and architecture notes live in [`docs/`](docs/).
----
+> **Beta** — actively built, expect rough edges and frequent updates. The software equivalent of
+> going to the gym for the first time.
## License
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 92d09bb..db10d8c 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -5,7 +5,7 @@ import tailwind from '@astrojs/tailwind';
// Deploys to Cloudflare Pages (served at the domain root). The workflow sets SITE_URL/SITE_BASE;
// these defaults keep local builds root-based too. Custom domain later = set SITE_URL=https://lyftr.dev.
-const site = process.env.SITE_URL || 'https://lyftr.pages.dev';
+const site = process.env.SITE_URL || 'https://lyftr-app.pages.dev';
const base = process.env.SITE_BASE ?? '/';
const ogImage = new URL('og-image.png', site).href;
@@ -33,10 +33,31 @@ export default defineConfig({
// The marketing landing lives at `/` (src/pages/index.astro); docs are served at
// their own slugs and linked from here.
sidebar: [
- { label: 'Getting Started', slug: 'getting-started' },
- { label: 'Self-Hosting', slug: 'self-hosting' },
- { label: 'Configuration', slug: 'configuration' },
- { label: 'FAQ', slug: 'faq' },
+ {
+ label: 'Start Here',
+ items: [{ label: 'Getting Started', slug: 'getting-started' }],
+ },
+ {
+ label: 'Self-Hosting',
+ items: [
+ { label: 'Install', slug: 'self-hosting' },
+ { label: 'Configuration', slug: 'configuration' },
+ { label: 'HTTPS & Reverse Proxy', slug: 'https' },
+ { label: 'Backups & Updates', slug: 'backups' },
+ { label: 'Troubleshooting', slug: 'troubleshooting' },
+ ],
+ },
+ {
+ label: 'Apps & Data',
+ items: [
+ { label: 'Mobile App', slug: 'mobile' },
+ { label: 'Exercise Library', slug: 'exercise-library' },
+ ],
+ },
+ {
+ label: 'Help',
+ items: [{ label: 'FAQ', slug: 'faq' }],
+ },
],
}),
// applyBaseStyles:false → don't inject Tailwind's base globally (it would fight
diff --git a/site/src/content/docs/backups.md b/site/src/content/docs/backups.md
new file mode 100644
index 0000000..e1a340f
--- /dev/null
+++ b/site/src/content/docs/backups.md
@@ -0,0 +1,65 @@
+---
+title: Backups & Updates
+description: Back up your Lyftr data (a single SQLite file) and update to the latest version safely.
+---
+
+All of your Lyftr data — workouts, programs, weight, nutrition — lives in **one SQLite file**.
+Backing up is copying that file. Updating is pulling the latest image. Your data survives both.
+
+## Where your data lives
+
+The database is stored on a Docker volume and mounted at `./data/lyftr.db` next to your
+`docker-compose.yml`. That single file *is* your instance.
+
+## Back up
+
+Copy the database file. For a personal instance with little write traffic, a live copy is fine:
+
+```bash
+cp ./data/lyftr.db ./data/lyftr.db.backup
+```
+
+For a guaranteed-consistent copy (e.g. right before an update), stop the stack first, then copy:
+
+```bash
+docker compose down
+cp ./data/lyftr.db ./data/lyftr.db.backup
+docker compose up -d
+```
+
+### Automate it (cron)
+
+A nightly backup keeping the last 7 days:
+
+```bash
+0 3 * * * cp /path/to/lyftr/data/lyftr.db /path/to/backups/lyftr-$(date +\%F).db && \
+ find /path/to/backups -name 'lyftr-*.db' -mtime +7 -delete
+```
+
+## Restore
+
+Stop the stack, drop the backup in place, start again:
+
+```bash
+docker compose down
+cp ./data/lyftr.db.backup ./data/lyftr.db
+docker compose up -d
+```
+
+## Update to the latest version
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Your data volume is preserved across updates.
+
+:::tip[Pin a stable version]
+Tracking `main` gets you the newest features but also the newest rough edges. For a stable
+self-host target, pin a released tag in your compose file instead of `latest`.
+:::
+
+:::note
+Back up **before** every update. It's one file — you have no excuse.
+:::
diff --git a/site/src/content/docs/exercise-library.md b/site/src/content/docs/exercise-library.md
new file mode 100644
index 0000000..7c231ee
--- /dev/null
+++ b/site/src/content/docs/exercise-library.md
@@ -0,0 +1,41 @@
+---
+title: Exercise Library
+description: Lyftr auto-seeds 800+ exercises on first startup from free-exercise-db — no API key, no setup.
+---
+
+Lyftr ships with an **800+ exercise library** that seeds itself automatically. No API key, no manual
+import, no setup.
+
+## Automatic seeding
+
+On first startup, Lyftr fetches the catalog from
+[free-exercise-db](https://github.com/yuhonas/free-exercise-db) in the background:
+
+```
+[startup] exercises table empty — fetching from free-exercise-db...
+[startup] seed: synced 868 exercises
+```
+
+The seed runs **async**, so the server is available immediately — exercises appear in the UI within
+a few seconds. Each exercise includes its muscle groups, equipment, category, and instructions.
+
+## Re-syncing
+
+To pull the latest exercises, go to **Settings → Exercise Library**. It shows the current exercise
+count and a progress indicator while seeding. Hit **Re-sync** to update.
+
+:::note[Your data is safe]
+Re-sync is a safe upsert — it updates the catalog without touching your logged workouts, sets, or
+history.
+:::
+
+## Empty list?
+
+If no exercises appear, check the logs and re-sync:
+
+```bash
+docker compose logs backend | grep -i seed
+```
+
+See [Troubleshooting](../troubleshooting/) if the seed can't reach GitHub (it needs outbound HTTPS
+on first run).
diff --git a/site/src/content/docs/getting-started.md b/site/src/content/docs/getting-started.md
index e40c6a6..2c06460 100644
--- a/site/src/content/docs/getting-started.md
+++ b/site/src/content/docs/getting-started.md
@@ -32,4 +32,6 @@ change anything — or register your own throwaway account.
- **[Self-Hosting](../self-hosting/)** — get your own instance running in one Docker command.
- **[Configuration](../configuration/)** — environment variables and the self-hosting gotchas.
+- **[HTTPS & Reverse Proxy](../https/)** — expose it publicly with automatic TLS.
+- **[Mobile App](../mobile/)** — install the Android app and point it at your server.
- **[FAQ](../faq/)** — common questions.
diff --git a/site/src/content/docs/https.md b/site/src/content/docs/https.md
new file mode 100644
index 0000000..c5e2030
--- /dev/null
+++ b/site/src/content/docs/https.md
@@ -0,0 +1,64 @@
+---
+title: HTTPS & Reverse Proxy
+description: Put Lyftr behind Caddy or nginx with automatic HTTPS (Let's Encrypt) for a public, secure instance.
+---
+
+Lyftr's container serves plain HTTP on a host port. To expose it publicly — and to use the **mobile
+app**, which needs a real hostname — put it behind a reverse proxy that terminates HTTPS.
+
+:::caution[Port conflict]
+By default the compose file publishes Lyftr on host port **80** (`PORT=80`). A reverse proxy also
+wants 80/443, so first move Lyftr to a different host port — set `PORT=8080` in your `.env` — and
+point the proxy at `localhost:8080`.
+:::
+
+## Caddy (easiest — automatic HTTPS)
+
+[Caddy](https://caddyserver.com) fetches and renews Let's Encrypt certificates for you. A one-line
+`Caddyfile`:
+
+```caddyfile
+lyftr.example.com {
+ reverse_proxy localhost:8080
+}
+```
+
+Then reload Caddy. That's it — HTTPS is live and auto-renewing.
+
+## nginx + Certbot
+
+```nginx
+server {
+ server_name lyftr.example.com;
+
+ location / {
+ proxy_pass http://localhost:8080;
+ proxy_set_header Host $host;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+}
+```
+
+Then issue a certificate with [Certbot](https://certbot.eff.org):
+
+```bash
+sudo certbot --nginx -d lyftr.example.com
+```
+
+## Point Lyftr at your public origin
+
+After the proxy is up, set `CORS_ORIGIN` to your HTTPS URL so browser and mobile clients are
+allowed, and restart:
+
+```bash
+# in .env
+CORS_ORIGIN=https://lyftr.example.com
+```
+
+```bash
+docker compose up -d
+```
+
+See [Configuration](../configuration/) for the full list of variables, and the
+[Mobile App](../mobile/) page for pointing the phone app at your new HTTPS server.
diff --git a/site/src/content/docs/mobile.md b/site/src/content/docs/mobile.md
new file mode 100644
index 0000000..50c26ad
--- /dev/null
+++ b/site/src/content/docs/mobile.md
@@ -0,0 +1,33 @@
+---
+title: Mobile App
+description: Install the Lyftr Android app, point it at your self-hosted server, and track workouts from your phone.
+---
+
+Lyftr has a native mobile app so you can log workouts at the gym, straight from your phone —
+talking to **your** server.
+
+## Android
+
+1. Download the latest signed APK from the
+ [Releases](https://github.com/Cawlumm/lyftr/releases?q=mobile-v) page.
+2. Open the `.apk` on your phone and allow **"install from unknown sources"** if prompted.
+3. Launch Lyftr and enter your server URL when asked.
+
+:::note[Side-loaded builds don't auto-update]
+When a new `mobile-v*` release drops, download and install it over the old one. Store builds with
+auto-update are on the roadmap.
+:::
+
+## Pointing the app at your server
+
+The app connects to your self-hosted instance, so it needs a URL it can actually reach:
+
+- **`localhost` won't work** from a phone — it refers to the phone itself.
+- On the same network, use your server's **LAN IP** (e.g. `http://192.168.1.10:8080`).
+- Best: a **real hostname over HTTPS** so it works anywhere — see [HTTPS & Reverse Proxy](../https/).
+- Make sure your server URL is in `CORS_ORIGIN` (see [Configuration](../configuration/)).
+
+## iOS
+
+Planned. Apple doesn't allow side-loading, so iOS will ship via **TestFlight** / the App Store once
+the Apple Developer account is set up. Watch the repo for updates.
diff --git a/site/src/content/docs/self-hosting.md b/site/src/content/docs/self-hosting.md
index 97d535e..26118ee 100644
--- a/site/src/content/docs/self-hosting.md
+++ b/site/src/content/docs/self-hosting.md
@@ -14,15 +14,22 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Cawlumm/lyftr/main/
curl -o .env https://raw.githubusercontent.com/Cawlumm/lyftr/main/.env.example
```
-Edit `.env` and set a strong `JWT_SECRET` (32+ characters), then bring it up:
+Edit `.env` and set a strong `JWT_SECRET` (32+ characters), then pull the prebuilt images and
+start:
```bash
+docker compose pull
docker compose up -d
```
Open `http://localhost` in your browser and create your account. On a VPS, replace `localhost`
with your server's IP or domain.
+:::note[Why `pull` first]
+The compose file references prebuilt images on Docker Hub. Running `docker compose pull` fetches
+them so nothing is built locally — you don't need the source code, just the compose file and `.env`.
+:::
+
:::tip[Exercise library]
On first startup Lyftr seeds **800+ exercises** from
[free-exercise-db](https://github.com/yuhonas/free-exercise-db) in the background — no API key, no
@@ -41,18 +48,10 @@ Tested and working on:
Single SQLite file, minimal RAM, no external services required.
-## Data & backups
-
-All of your data lives in one SQLite file on a Docker volume. Backing up is copying that file —
-see [Configuration](../configuration/) for the exact paths and environment variables.
-
-## Updating
-
-Pull the latest images and recreate the containers:
-
-```bash
-docker compose pull
-docker compose up -d
-```
+## Next steps
-Your data volume is preserved across updates.
+- **[Configuration](../configuration/)** — environment variables (`JWT_SECRET`, `CORS_ORIGIN`, ports).
+- **[HTTPS & Reverse Proxy](../https/)** — expose it publicly with automatic TLS (and to use the mobile app).
+- **[Backups & Updates](../backups/)** — protect your data and upgrade safely.
+- **[Mobile App](../mobile/)** — install the Android app and point it at your server.
+- **[Troubleshooting](../troubleshooting/)** — fixes for `502`, ports, and connectivity.
diff --git a/site/src/content/docs/troubleshooting.md b/site/src/content/docs/troubleshooting.md
new file mode 100644
index 0000000..564cfc6
--- /dev/null
+++ b/site/src/content/docs/troubleshooting.md
@@ -0,0 +1,58 @@
+---
+title: Troubleshooting
+description: Fixes for the most common Lyftr self-hosting issues — 502 errors, login, ports, and exercise seeding.
+---
+
+The common issues, and how to fix them.
+
+## `502 Bad Gateway` after loading the page
+
+Almost always `BACKEND_ORIGIN` pointing at the wrong place. It's resolved over the **internal Docker
+network**, so it must use the backend's **service name** (`backend`), not your host or LAN IP.
+
+```
+connect() failed (111: Connection refused)
+```
+
+Pointing it at something like `192.168.1.10:3000` fails because the backend isn't published to the
+host — only exposed on the Docker network. Fix: leave it as `backend:3000`, or change **only the
+port** if you set a custom backend `PORT` (e.g. `backend:3008`). See [Configuration](../configuration/).
+
+## Login fails / tokens rejected
+
+Make sure `JWT_SECRET` is set to a strong value (32+ characters) in `.env` and that you restarted
+after changing it:
+
+```bash
+docker compose up -d
+```
+
+Changing `JWT_SECRET` invalidates existing sessions — log in again.
+
+## Port already in use
+
+If host port 80 is taken (another web server, or a reverse proxy), move Lyftr to a free port with
+`PORT=8080` in `.env`, then restart. If you're running a reverse proxy, see
+[HTTPS & Reverse Proxy](../https/).
+
+## The mobile app or another device can't connect
+
+- The app needs a reachable server URL — `localhost` won't work from a phone. Use your server's LAN
+ IP or, better, a real hostname over HTTPS ([reverse proxy](../https/)).
+- Add that origin to `CORS_ORIGIN` (comma-separated), or use `*` to allow any (the API is
+ Bearer-token based, so there are no cookies to protect).
+
+## No exercises show up
+
+They seed in the background on first startup and appear within a few seconds. If the list is empty,
+check the logs and use **Settings → Exercise Library → Re-sync**. See
+[Exercise Library](../exercise-library/).
+
+```bash
+docker compose logs backend | grep -i seed
+```
+
+## Still stuck?
+
+Open an issue on [GitHub](https://github.com/Cawlumm/lyftr/issues) or ask in the
+[Discord](https://discord.gg/hfFWsrebQA) — include your `docker compose logs` output.
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
index 098f887..507160a 100644
--- a/site/src/pages/index.astro
+++ b/site/src/pages/index.astro
@@ -27,10 +27,10 @@ const ogImage = new URL(banner.src, Astro.site).href;
const logoUrl = new URL('logo.svg', Astro.site).href;
const proof = [
- '160+ GitHub stars',
- 'Featured in selfh.st',
- 'Runs on Pi · NAS · $5 VPS',
- 'MIT · Free · No subscription',
+ { label: '160+ GitHub stars', href: REPO },
+ { label: 'Featured in selfh.st', href: 'https://selfh.st/weekly/2026-04-24/' },
+ { label: 'Runs on Pi · NAS · $5 VPS' },
+ { label: 'MIT · Free · No subscription' },
];
const features = [
@@ -44,16 +44,14 @@ const features = [
{ t: 'Nutrition tracking', d: 'Calories, macros, barcode scan, and food search.' },
];
-// Comparison — honest. true / false / 'partial'
-const cols = ['Lyftr', 'Hevy', 'Strong', 'Wger'];
-const rows: { label: string; v: (boolean | 'partial')[] }[] = [
- { label: 'Self-hosted', v: [true, false, false, true] },
- { label: 'Open source', v: [true, false, false, true] },
- { label: 'Free / no subscription', v: [true, false, false, true] },
- { label: 'Own your data', v: [true, false, false, true] },
- { label: 'Mobile-first UI', v: [true, true, true, 'partial'] },
- { label: 'Nutrition tracking', v: [true, false, false, true] },
- { label: 'One-command Docker', v: [true, false, false, 'partial'] },
+// Why self-host — the value props (no competitor comparison).
+const values = [
+ { t: 'Self-hosted', d: 'Your data never leaves your server — no cloud account required.' },
+ { t: 'Open source (MIT)', d: 'No black box. Read it, fork it, audit it, extend it.' },
+ { t: 'Free forever', d: 'No subscription and no paywalled features. All of it, always.' },
+ { t: 'Own your data', d: 'Everything lives in one SQLite file you fully control.' },
+ { t: 'Mobile-first', d: 'A native Android app plus a fast, responsive web UI.' },
+ { t: 'One-command deploy', d: 'Up and running with Docker in a couple of minutes.' },
];
const runsOn = ['Raspberry Pi 4', 'Hetzner / DigitalOcean / Oracle', 'Synology NAS', 'Proxmox LXC', 'Mac · Linux · Windows'];
@@ -200,45 +198,26 @@ const jsonLd = {
{proof.map((p) => (
<span class="flex items-center gap-2">
<svg class="h-4 w-4 text-brand-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" d="M16.7 5.3a1 1 0 010 1.4l-7.5 7.5a1 1 0 01-1.4 0L3.3 9.7a1 1 0 011.4-1.4l3.3 3.3 6.8-6.8a1 1 0 011.4 0z" clip-rule="evenodd"/></svg>
- {p}
+ {p.href ? <a href={p.href} class="transition hover:text-brand-300">{p.label}</a> : p.label}
</span>
))}
</div>
</section>
- <!-- Comparison -->
+ <!-- Why self-host -->
<section class="mx-auto max-w-6xl px-5 py-20">
- <h2 class="text-center font-display text-3xl font-bold tracking-tight sm:text-4xl">The open-source Hevy &amp; Strong alternative</h2>
- <p class="mx-auto mt-3 max-w-2xl text-center text-tx-secondary">The honest comparison. Great apps exist — Lyftr's bet is self-hosted, open-source, and free.</p>
- <div class="mt-10 overflow-x-auto">
- <table class="w-full min-w-[560px] border-separate border-spacing-0 overflow-hidden rounded-2xl border border-surface-border">
- <thead>
- <tr>
- <th class="bg-surface-raised px-4 py-4 text-left text-sm font-semibold text-tx-muted">Feature</th>
- {cols.map((c, i) => (
- <th class={`px-4 py-4 text-center text-sm font-bold ${i === 0 ? 'bg-brand-500/10 text-brand-300' : 'bg-surface-raised text-tx-secondary'}`}>{c}</th>
- ))}
- </tr>
- </thead>
- <tbody>
- {rows.map((r, ri) => (
- <tr>
- <td class={`px-4 py-3.5 text-sm font-medium text-tx-primary ${ri % 2 ? 'bg-surface-raised/40' : ''}`}>{r.label}</td>
- {r.v.map((val, ci) => (
- <td class={`px-4 py-3.5 text-center ${ci === 0 ? 'bg-brand-500/5' : ''} ${ri % 2 ? 'bg-surface-raised/40' : ''}`}>
- {val === true ? (
- <span class="text-brand-400" aria-label="Yes">✓</span>
- ) : val === 'partial' ? (
- <span class="text-warning-400" aria-label="Partial">~</span>
- ) : (
- <span class="text-tx-muted" aria-label="No">✗</span>
- )}
- </td>
- ))}
- </tr>
- ))}
- </tbody>
- </table>
+ <h2 class="text-center font-display text-3xl font-bold tracking-tight sm:text-4xl">Why self-host Lyftr?</h2>
+ <p class="mx-auto mt-3 max-w-2xl text-center text-tx-secondary">A modern workout tracker that's yours — open, free, and running on your own server.</p>
+ <div class="mt-10 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+ {values.map((v) => (
+ <div class="rounded-xl border border-surface-border bg-surface-raised p-5">
+ <div class="flex items-center gap-2">
+ <svg class="h-5 w-5 shrink-0 text-brand-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" d="M16.7 5.3a1 1 0 010 1.4l-7.5 7.5a1 1 0 01-1.4 0L3.3 9.7a1 1 0 011.4-1.4l3.3 3.3 6.8-6.8a1 1 0 011.4 0z" clip-rule="evenodd"/></svg>
+ <h3 class="font-display text-base font-bold text-tx-primary">{v.t}</h3>
+ </div>
+ <p class="mt-1.5 text-sm text-tx-secondary">{v.d}</p>
+ </div>
+ ))}
</div>
</section>