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.

Follow-up to #304: the Kubernetes guide is linked from the self-hosting guide, the gateway may read the certificate, and the manifests say what to set

Duarte Santos495ee318eb81
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index d5fe7c2e6..cffe12355 100644
--- a/docs/SELF_HOSTING.md
+++ b/docs/SELF_HOSTING.md
@@ -292,6 +292,9 @@ from Settings → "Pair the mobile app", as with a passkey.
## 5. Fitting it into an existing stack
+Running Kubernetes? Example manifests (Deployment, PVCs, Service, Gateway API route) are in
+`kubernetes/`, described in [SELF_HOSTING_KUBERNETES.md](SELF_HOSTING_KUBERNETES.md).
+
The defaults assume openGym is the only thing here: a service called `api` on port 3000, and nginx
on port 80 inside its container. If you are merging this into a compose file that already has an
`api`, or you put the web container behind your own reverse proxy on a different port, four
diff --git a/docs/SELF_HOSTING_KUBERNETES.md b/docs/SELF_HOSTING_KUBERNETES.md
index b7cbc6365..3efc12c85 100644
--- a/docs/SELF_HOSTING_KUBERNETES.md
+++ b/docs/SELF_HOSTING_KUBERNETES.md
@@ -1,19 +1,38 @@
# Self-hosting openGym on Kubernetes
+Example manifests for a small cluster, contributed from a K3s setup with the Gateway API and
+cert-manager. Read [SELF_HOSTING.md](SELF_HOSTING.md) first: the passkey requirement (HTTPS,
+`RP_ID`, `ORIGIN`), the settings in `.env.example` and the backup advice apply here unchanged.
-openGym is pretty simple - a frontend and an API backend. The API keeps everything in a plain JSON file on a volume. The Docker Compose file also has a third container that syncs a bunch of media files, which I have chosen to implement as an initContainer.There are only a few resources to create:
+openGym is pretty simple — a frontend and an API backend. The API keeps everything in plain JSON
+files on a volume. The Docker Compose file also has a third container that downloads the exercise
+media once; here that is an initContainer. There are only a few resources to create:
-- 2 PVCs: data and media
-- 1 deployment for the API and web interface: I decided to keep them in a single pod for simplicity.
-- An HTTPRoute or an Ingress - you really should be using an HTTPRoute nowadays.
-
-There are example manifests available:
+- 2 PVCs: `opengym-data` (users, passkeys, workouts, uploads — **back this one up**) and
+ `opengym-media` (the exercise images, downloaded again if lost).
+- 1 Deployment running the API and the web container in a single pod, for simplicity. It stays at
+ one replica with the `Recreate` strategy: the API's data is files on a `ReadWriteOnce` volume,
+ and two API processes must never write them at once.
+- An HTTPRoute (the example uses the Gateway API; an Ingress to the `opengym` Service on port 80
+ works as well), plus a cert-manager Certificate for the hostname.
```bash
git clone https://github.com/DuarteSantos8/openGym # or https://gitlab.com/DuarteSantos8/opengym — same repo
-cd openGym
-# edit the spec.template.env.containers["api"].env with at least your URL
+cd openGym
+# In kubernetes/deployment.yaml, set RP_ID and ORIGIN in spec.template.spec.containers[api].env
+# to your hostname, and the hostname in kubernetes/httproute.yaml.
kubectl apply -k kubernetes/
```
-You will also need an API Gateway, that is configured to work with TLS. It has been tested with [Envoy Gateway](https://gateway.envoyproxy.io) and [Cert-Manager](https://cert-manager.io).
+Notes:
+
+- The manifests use the `fitness` namespace (`kubernetes/kustomization.yaml`) and a Gateway
+ called `eg` in `envoy-gateway-system` with an `https` listener; change both to match your
+ cluster. The Gateway has to terminate TLS; this was tested with
+ [Envoy Gateway](https://gateway.envoyproxy.io) and [cert-manager](https://cert-manager.io).
+- The images are the published `ghcr.io/duartesantos8/opengym-api` and `opengym-web`. The AI
+ Coach with an API key works on that same API image; the Claude and Codex sign-in providers
+ need the `coach` build target, which is not published — build it yourself (see
+ [AI_COACH.md](AI_COACH.md)).
+- Settings are environment variables on the `api` container, named as in `.env.example`. Keep
+ secrets such as the push keys in a Kubernetes Secret and load them with `envFrom`.
diff --git a/kubernetes/deployment.yaml b/kubernetes/deployment.yaml
index 39d44cce4..e1d350229 100644
--- a/kubernetes/deployment.yaml
+++ b/kubernetes/deployment.yaml
@@ -17,6 +17,10 @@ spec:
app: opengym
spec:
initContainers:
+ # The exercise images and GIFs, one time (~140 MB) — the same download as the media
+ # service in docker-compose.yml. They are © Gym visual (https://gymvisual.com/), used
+ # under the exercises-dataset's terms and fetched from upstream, not redistributed by
+ # openGym; see NOTICE.md.
- name: media-download
image: alpine/git
command: ["/bin/sh", "-c"]
@@ -48,6 +52,8 @@ spec:
value: opengym.example.com
- name: ORIGIN
value: https://opengym.example.com
+ # Everything else in .env.example (INVITE_ONLY, ADMIN_UIDS, ALLOW_GUEST,
+ # DEFAULT_LANG, PASSWORD_LOGIN, the push keys, ...) goes here the same way.
ports:
- containerPort: 3000
name: http
@@ -75,6 +81,8 @@ spec:
env:
- name: NGINX_PORT
value: "80"
+ # Both containers share the pod's network, so the API is on localhost. An IP here
+ # also means nginx never needs RESOLVER (Docker's DNS by default) to find it.
- name: BACKEND
value: 127.0.0.1
- name: PORT
diff --git a/kubernetes/httproute.yaml b/kubernetes/httproute.yaml
index ca7ae0500..906e257df 100644
--- a/kubernetes/httproute.yaml
+++ b/kubernetes/httproute.yaml
@@ -3,7 +3,6 @@ apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: opengym-tls
- namespace: fitness
spec:
dnsNames:
- opengym.example.com
@@ -12,6 +11,10 @@ spec:
name: letsencrypt
secretName: opengym-tls
---
+# The Gateway lives in another namespace, and its HTTPS listener has to read the certificate
+# above: a cross-namespace reference to a Secret needs this grant. The route below points at a
+# Service in its own namespace and needs none. Drop this if your listener carries its own
+# (e.g. wildcard) certificate.
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
@@ -23,7 +26,8 @@ spec:
namespace: envoy-gateway-system
to:
- group: ""
- kind: Service
+ kind: Secret
+ name: opengym-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
diff --git a/kubernetes/kustomization.yaml b/kubernetes/kustomization.yaml
index 112d20caa..9a22bdfd5 100644
--- a/kubernetes/kustomization.yaml
+++ b/kubernetes/kustomization.yaml
@@ -6,4 +6,4 @@ resources:
- pvc.yaml
- deployment.yaml
- service.yaml
- - httproute.yaml
\ No newline at end of file
+ - httproute.yaml