Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

Docs: self-hosting on a Mac with Colima and Tailscale Serve

Adrián Fernández34f74f5cf6dd
diff --git a/README.md b/README.md
index 367f758c2..633585a40 100644
--- a/README.md
+++ b/README.md
@@ -155,7 +155,7 @@ part of the image, so there's nothing else to download.
To reach it from your phone with passkeys you need HTTPS on a domain; that's a two-line change in
`.env`. The [self-hosting guide](docs/SELF_HOSTING.md) walks through Cloudflare Tunnel, Caddy,
Traefik and nginx, and there are separate guides for
-[HTTPS on a LAN](docs/SELF_HOSTING_HTTPS.md) and [Kubernetes](docs/SELF_HOSTING_KUBERNETES.md).
+[HTTPS on a LAN](docs/SELF_HOSTING_HTTPS.md), [a Mac with Tailscale](docs/SELF_HOSTING_MAC.md) and [Kubernetes](docs/SELF_HOSTING_KUBERNETES.md).
> [!NOTE]
> Images are published from the same tag to `ghcr.io/duartesantos8/opengym-{api,web}`
diff --git a/docs/README.md b/docs/README.md
index 03f623980..81afb9669 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,7 @@ to install.
|---|---|
| [Self-hosting](SELF_HOSTING.md) | You're setting up an instance. Start here: running it, passkeys and HTTPS, users, backups, updates, troubleshooting |
| [HTTPS at home](SELF_HOSTING_HTTPS.md) | You want valid certificates on your LAN without exposing the server to the internet |
+| [On a Mac](SELF_HOSTING_MAC.md) | You want to run it on a Mac at home, with Colima instead of Docker Desktop and Tailscale for HTTPS |
| [Kubernetes](SELF_HOSTING_KUBERNETES.md) | You run a cluster instead of Docker Compose |
| [AI coach](AI_COACH.md) | You're deciding whether to turn the coach on, and with which provider |
| [MCP server](../mcp/README.md) | You want Claude Desktop, Cursor or another AI client to read your training history |
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index c009c1c61..1f1b84ae2 100644
--- a/docs/SELF_HOSTING.md
+++ b/docs/SELF_HOSTING.md
@@ -17,8 +17,8 @@ This guide takes you from "just cloned it" to "using it from my phone over the i
- [Which passkey providers work](#which-passkey-providers-work)
- [Troubleshooting](#troubleshooting)
-HTTPS on a LAN without a public domain has [its own guide](SELF_HOSTING_HTTPS.md), and so does
-[Kubernetes](SELF_HOSTING_KUBERNETES.md). Short answers to common questions are in the [FAQ](FAQ.md).
+HTTPS on a LAN without a public domain has [its own guide](SELF_HOSTING_HTTPS.md), and so do
+[a Mac at home with Tailscale](SELF_HOSTING_MAC.md) and [Kubernetes](SELF_HOSTING_KUBERNETES.md). Short answers to common questions are in the [FAQ](FAQ.md).
## 1. Run it locally (5 minutes)
diff --git a/docs/SELF_HOSTING_MAC.md b/docs/SELF_HOSTING_MAC.md
new file mode 100644
index 000000000..0f20c2b62
--- /dev/null
+++ b/docs/SELF_HOSTING_MAC.md
@@ -0,0 +1,117 @@
+# openGym on a Mac at home (Colima and Tailscale)
+
+A way to run openGym on a spare Mac, with no Docker Desktop, no domain and no reverse proxy.
+[Colima](https://github.com/abiosoft/colima) runs the containers, and
+[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) gives the server an `https://` address
+that your phone can use for passkeys and pairing. The address only works inside your own tailnet
+(your devices on Tailscale), so nothing is open to the internet.
+
+This page only covers what is different on a Mac. The rest (users, backups, settings) is in
+[SELF_HOSTING.md](./SELF_HOSTING.md).
+
+## What you need
+
+- A Mac that can stay on, with [Homebrew](https://brew.sh).
+- A free [Tailscale](https://tailscale.com) account, with Tailscale installed on the Mac **and** on your phone.
+- About 2 GB of RAM and 20 GB of disk to spare for the Colima VM.
+
+## 1. Docker without Docker Desktop
+
+```bash
+brew install colima docker docker-compose
+colima start --cpu 2 --memory 2 --disk 20 # once: the sizes are remembered
+brew services start colima # starts it at login from now on
+```
+
+Homebrew's `docker-compose` is a CLI plugin. Tell the `docker` command where it is by adding this to
+`~/.docker/config.json` (create the file if it does not exist):
+
+```json
+{ "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"] }
+```
+
+(`/usr/local/lib/docker/cli-plugins` on an Intel Mac.) Check with `docker compose version`.
+
+## 2. Get openGym
+
+Clone it somewhere that is **not** iCloud Drive or another synced folder (`~/Dev/opengym` works). The
+`./data` folder is written all the time and does not like being synced.
+
+```bash
+git clone https://github.com/DuarteSantos8/openGym ~/Dev/opengym
+cd ~/Dev/opengym
+cp .env.example .env
+```
+
+## 3. Turn on HTTPS in Tailscale
+
+Once per tailnet, in the [admin console](https://login.tailscale.com/admin/dns): make sure **MagicDNS** is
+on, then under **HTTPS Certificates** choose **Enable HTTPS**.
+
+Tailscale lists the names of your machines in public certificate logs when it does this. If your Mac's
+name says something private, rename it first.
+
+Your Mac's address is `https://<your-mac>.<your-tailnet>.ts.net`. You can read it in the Tailscale
+menu, or in the output of `tailscale serve status` after the next step.
+
+## 4. Point `.env` at that address
+
+Edit `.env` and set the two values to your address, without a trailing slash:
+
+```
+RP_ID=<your-mac>.<your-tailnet>.ts.net
+ORIGIN=https://<your-mac>.<your-tailnet>.ts.net
+FIRST_USER_ADMIN=1
+```
+
+`RP_ID` is only the host name, `ORIGIN` is the full address. Passkeys are tied to `RP_ID`, so pick it now:
+changing it later makes the existing passkeys useless (see
+[the passkey requirement](./SELF_HOSTING.md#2-understand-the-passkey-requirement-important)).
+
+Then start the server and publish it:
+
+```bash
+docker compose pull
+docker compose up -d
+tailscale serve --bg 8080
+```
+
+`--bg` keeps the Serve setting across reboots. `tailscale serve status` shows what is published, and
+`tailscale serve reset` removes it. If you changed `WEB_PORT`, use that port instead of 8080.
+
+Open your `https://` address in a browser **on a device with Tailscale on**, and create your profile.
+The first profile becomes the admin. Once it exists, add `INVITE_ONLY=1` to `.env` and run
+`docker compose up -d` again, so nobody else on your tailnet can add a profile
+(see [Multiple users](./SELF_HOSTING.md#4-multiple-users)).
+
+## 5. Pair the phone
+
+1. On the phone, turn Tailscale on.
+2. In the browser where you are signed in: Settings, Account, **Pair the mobile app**. You get an
+ 8-character code that lasts 5 minutes.
+3. In the openGym app: Settings, Account, **Connect to my server**. Enter your `https://` address and the
+ code.
+
+More on pairing in [MOBILE.md](./MOBILE.md).
+
+## 6. Updating
+
+```bash
+cd ~/Dev/opengym
+git pull
+docker compose pull
+docker compose up -d
+```
+
+## Limits
+
+- **The Mac has to be on and awake** for the phone to sync. Set it not to sleep when plugged in
+ (System Settings, Energy). The phone keeps working without it and sends its changes when the server
+ is back.
+- **Only your tailnet can reach it.** Anyone you want to share with needs to be on your tailnet, or you
+ need another way in (see [SELF_HOSTING.md](./SELF_HOSTING.md#3-expose-it-over-https-on-your-own-domain)).
+ The phone needs Tailscale turned on to sync, also when you are at home.
+- Docker still publishes port 8080 on the Mac itself, so it is also open as plain `http://` to your home
+ network. Tailscale is not required for that, but passkeys will not work there.
+- Back up `./data` as described in [Backups](./SELF_HOSTING.md#6-backups). The Colima VM itself holds nothing
+ you need.