Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker & Docker Compose

Required for running all services in containers

Git

For cloning the repository
For local development without Docker, you’ll also need Python 3.13+, Node.js 22+, PostgreSQL 18, and Redis 8.

​
Quick Start with Docker

Get up and running in 3 simple steps:
1

Clone and Navigate

Clone the repository and navigate to the project directory:
git clone https://github.com/yocxy2/open-wearables.git
cd open-wearables
2

Configure Environment

Copy the example environment files to create your local configuration:
cp ./backend/config/.env.example ./backend/config/.env
The default configuration works out of the box for local development. You can customize settings later for provider integrations.
3

Start the Platform

Launch all services with a single command:
docker compose up -d
This starts 6 services:
  • PostgreSQL (port 5432) - Database
  • Redis (port 6379) - Cache and message broker
  • FastAPI Backend (port 8000) - REST API
  • Celery Worker - Background task processor
  • Celery Beat - Task scheduler
  • React Frontend (port 3000) - Developer portal
  • Flower (port 5555) - Celery monitoring dashboard
First launch takes 2-3 minutes to build Docker images. Subsequent starts are faster.

​
Access the Platform

Once all services are running, you can access:

Developer Portal

Web dashboard for managing users and API keysDefault credentials:

API Documentation

Interactive Swagger UI for exploring and testing API endpoints

Celery Dashboard

Monitor background tasks and workers via Flower

API Root

Direct API access at http://localhost:8000/api/v1/

​
Seed Sample Data (Optional)

To test the platform with sample users and activity data: 
make seed
This creates:
  • Multiple test users with different connection states
  • Sample workout data across multiple providers
  • Time series data for heart rate, steps, and other metrics
The seed command requires the backend container to be running. Make sure you’ve completed the Quick Start steps first.

​
Verify Installation

Check that all services are healthy: 
docker compose ps
Expected output from the API test: 
{
  "message": "Server is running!"
}

​
Next Steps

Architecture Overview

Understand how the platform components work together

API Reference

Explore available API endpoints and data models

Connect Providers

Set up OAuth for Garmin, Polar, Suunto, and more

Developer Guide

Learn how to extend the platform

​
Local Development Setup

For active development without Docker:
1

Install Dependencies

Requires Python 3.13+ with uv package manager:
cd backend
uv sync
2

Start Infrastructure

Start PostgreSQL and Redis only:
docker compose up db redis -d
3

Run Database Migrations

Initialize the database schema:
cd backend
uv run alembic upgrade head
4

Start Development Servers

cd backend
uv run uvicorn app.main:api --reload --host 0.0.0.0 --port 8000

​
Useful Commands

Common Makefile commands for managing the platform:
CommandDescription
make buildRebuild Docker images from scratch
make runStart all services in detached mode
make stopStop all running containers
make downStop and remove all containers
make watchStart with hot-reload for development
make testRun backend test suite
make migrateApply database migrations
make create_migration m="Description"Create a new migration
make downgradeRollback the last migration
make seedPopulate database with sample data
make reset_db⚠️ WARNING: Delete all data

​
Troubleshooting

If you see “address already in use” errors, check what’s using the ports:
# Check ports 3000, 5432, 6379, 8000
lsof -i :3000
lsof -i :5432
lsof -i :6379
lsof -i :8000
Stop the conflicting service or modify the port mappings in docker-compose.yml.
Ensure PostgreSQL is healthy before the backend starts:
docker compose logs db
docker compose restart app
Verify the backend URL in frontend/.env:
VITE_API_URL=http://localhost:8000
After changing environment variables, restart the frontend container:
docker compose restart frontend
If you encounter permission issues with volumes:
sudo chown -R $USER:$USER .
docker compose down -v
docker compose up -d

​
Environment Variables

Key configuration options in backend/config/.env:
​
ADMIN_EMAIL
string
default:"[email protected]"
Email for the auto-created admin account
​
ADMIN_PASSWORD
string
default:"your-secure-password"
Password for the admin account (change this in production!)
​
SECRET_KEY
string
required
JWT signing key. Generate with:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
​
CORS_ORIGINS
array
default:"[\"http://localhost:3000\"]"
Allowed origins for CORS. Add your production frontend URL here.
​
SYNC_INTERVAL_SECONDS
integer
default:"3600"
How often to sync data from connected providers (in seconds)
Provider-specific credentials (Garmin, Polar, Suunto, etc.) are configured in the same .env file. See the Provider Integration guide for setup instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us