1. The Core Bottleneck
Traditional fitness tracking applications rely heavily on closed-source cloud infrastructure. User training history, progressive overload metrics, and body composition data remain locked inside vendor-controlled servers. When companies sunset products or alter subscription models, historical data vanishes. Commercial SaaS apps also inject telemetry scrapers, subscription pop-ups, and forced login walls into the training loop. openGym eliminates the cloud middleman entirely by championing self-hosting. It strips away external authentication dependencies, leveraging WebAuthn protocols for hardware-backed Passkey logins. Workout routines and body-weight logs reside inside a local folder controlled directly by the engineer, providing modern PWA offline support and cross-device synchronization without compromising data ownership.
💡 Architectural Insight: By decoupling local file storage from cryptographic identity verification, openGym delivers a modern cloud-native web application experience while guaranteeing zero third-party telemetry or server dependency.
2. Architecture & Data Flow Analysis
openGym adopts a lightweight, self-contained architecture that bypasses complex microservice overhead. The frontend runs as a Progressive Web App capable of full offline operations via Service Workers. Read and write operations commit directly to local mounted storage volumes rather than traveling through remote API gateways. During multi-device synchronization, the system resolves concurrent edits through field-level merge strategies rather than relying on heavy central relational database locking.
[ Client PWA / Browser ] ---> [ Passkey WebAuthn Auth ] ---> [ Local SQLite / JSON Vol ]
│
▼
[ Optional AI Coach / MCP ] ---> [ Local LLM / Ollama API ]
The codebase bundles an extensive exercise library alongside multimodal workout metrics. The optional AI Coach operates inside an isolated sandbox, interacting solely as an assistive agent rather than a control plane. Users can hook in Anthropic, OpenAI, or local Ollama instances via custom API keys to draft weekly routines. Every AI-suggested modification requires explicit human approval before committing to the active training ledger.
3. Technology Selection & Hardcore Comparison
| Evaluation Dimension | openGym (This Project) | Commercial Fitness SaaS | Traditional Spreadsheet | Production Engineering Yield |
|---|---|---|---|---|
| Data Ownership | User-controlled local directory | Third-party cloud servers | Local cold storage files | Eliminates third-party data breach vectors |
| Authentication | Passkey (Face ID/Touch ID) | Email & Password / OAuth | None / Physical locks | Hardware-grade crypto, zero credential leaks |
| Deployment Overhead | Single docker compose up |
Zero-deploy SaaS model | Manual formula maintenance | 5-minute private cluster delivery |
| Offline Resilience | PWA offline sync, P2P merge | Frequent loading spinners | Absolute offline, zero sync | Zero interruptions in weak cellular zones |
| AI Extensibility | Local Ollama / Custom API Key | Closed-source locked algorithms | None | Zero data leakage local LLM integration |
This technology stack lowers the barrier of entry for private fitness infrastructure. Unlike enterprise systems requiring Kubernetes clusters, openGym consumes minimal RAM, running efficiently on low-power devices like Raspberry Pi or Synology NAS.
4. Hands-on Geek Guide: Zero to Minimum Viable Loop
Deploying openGym on a production server or local developer machine requires a standard Docker runtime. The following workflow initializes a production-ready container instance.
Create a docker-compose.yml configuration file with the following orchestration parameters:
version: '3.8'
services:
opengym:
image: ghcr.io/duartesantos/opengym:latest # Pulls the official pre-built stable release image
container_name: opengym_production # Assigns a deterministic container name for log tracing
restart: unless-stopped # Automatically restarts on system reboot or crash
ports:
- "8080:80" # Maps host port 8080 to container internal port 80
volumes:
- ./data:/app/data # Mounts local data directory into container for persistence
environment:
- AUTH_PASSKEYS_ENABLED=true # Enables hardware-backed Passkey cryptographic authentication
- TZ=Asia/Shanghai # Synchronizes container runtime timezone with local training logs
Run the execution command and verify the logs in the terminal:
# Starts the daemon container in the background within the compose file directory
docker compose up -d
# Tails live container execution logs to confirm successful database initialization
docker compose logs -f opengym
Once the service boots up, access http://localhost:8080 via browser. The initial interface guides through hardware Passkey registration, allowing immediate CSV data imports or routine creation.
5. Production Gotchas & Failure Mitigation
Deploying openGym in self-hosted environments requires attention to specific infrastructure constraints to prevent data loss or authentication lockouts.
⚠️ Gotcha Warning [Unmapped Volume Risk]: Omitting the
./data:/app/datavolume mapping inside thedocker-compose.ymlfile causes SQLite database wipes during container rebuilds. Always verify host directory write permissions.⚠️ Gotcha Warning [HTTPS & Passkey Enforcement]: The WebAuthn protocol strictly enforces secure contexts in production. Accessing the instance over raw HTTP IP addresses (excluding
localhost) triggers browser security blocks against Passkey prompts. Always front the container with an Nginx reverse proxy running valid SSL certificates, or access it securely via Tailscale overlays.
