Skip to main content

​
Local Development Setup

This guide walks you through setting up your local development environment for Open Wearables, a health and wearable data aggregation platform.

​
Prerequisites

Before starting, ensure you have the following installed:

Docker

Recommended for quickest setup with all services

uv

Python package manager that automatically manages Python versions

pnpm

Fast, disk space efficient Node.js package manager

Node.js 22+

Required for frontend development without Docker
Docker is strongly recommended as it sets up PostgreSQL, Redis, Celery workers, and all services with a single command.

​
Quick Start with Docker

The fastest way to get started is using Docker Compose with hot-reload enabled:
1

Clone the repository

git clone https://github.com/yocxy2/open-wearables.git
cd open-wearables
2

Start all services with hot-reload

make watch
This starts:
  • PostgreSQL database
  • Redis cache
  • FastAPI backend with auto-reload
  • React frontend with HMR (Hot Module Replacement)
  • Celery worker for background tasks
  • Flower for task monitoring
An admin account is automatically created on startup:
3

Seed sample data (optional)

make seed
This populates the database with test users, workouts, and health data for development.

​
Access Points

Once the services are running, you can access:
ServiceURLDescription
Frontendhttp://localhost:3000React UI application
Backend APIhttp://localhost:8000FastAPI backend
API Documentationhttp://localhost:8000/docsInteractive Swagger UI
Celery Flowerhttp://localhost:5555Task queue monitoring

​
Makefile Commands

The project includes a Makefile with convenient commands:
CommandDescription
make buildBuild Docker images
make runStart in detached mode
make upStart in foreground (see logs)
make watchStart with hot-reload (recommended for development)
make stopStop containers
make downStop and remove containers
CommandDescription
make migrateApply database migrations
make create_migration m="description"Create new migration
make seedSeed sample test data
CommandDescription
make testRun backend test suite

​
Local Development Without Docker

If you prefer to run services locally without Docker:

​
Backend Setup

1

Navigate to backend directory

cd backend
2

Install dependencies with uv

uv sync
This creates a virtual environment and installs all Python dependencies from pyproject.toml.
3

Configure environment variables

cp config/.env.example config/.env
Edit config/.env to match your local setup (database credentials, API keys, etc.).
4

Run database migrations

uv run alembic upgrade head
5

Start the development server

uv run fastapi dev app/main.py --host 0.0.0.0 --port 8000
The backend will be available at http://localhost:8000 with auto-reload enabled.
You’ll need PostgreSQL running locally. Install PostgreSQL and create a database named open_wearables before running migrations.

​
Frontend Setup

1

Navigate to frontend directory

cd frontend
2

Install dependencies

pnpm install
3

Configure environment variables

cp .env.example .env
Update the API URL if your backend runs on a different port.
4

Start development server

pnpm dev
The frontend will be available at http://localhost:3000 with hot module replacement.

​
Environment Variables

Both backend and frontend require environment configuration:

​
Backend Environment

Copy backend/config/.env.example to backend/config/.env and configure: 
DATABASE_URL=postgresql://open-wearables:open-wearables@localhost:5432/open_wearables
DATABASE_TEST_URL=postgresql://open-wearables:open-wearables@localhost:5432/open_wearables_test

​
Frontend Environment

Copy frontend/.env.example to frontend/.env: 
VITE_API_URL=http://localhost:8000

​
Viewing Logs

Monitor application logs while developing: 
docker compose logs -f app

​
Development Workflow Resources

For detailed code patterns and architecture guidelines:

Backend Patterns

Python/FastAPI patterns, repository layer, service layer, and routes

Frontend Patterns

React/TypeScript patterns, TanStack Router, React Query, and forms

Contributing Guide

Pull request guidelines, code quality, and testing requirements

Adding Providers

Step-by-step guide to integrating new wearable data providers

​
Troubleshooting

If you see port conflicts, check for running services:
# Check what's using port 8000
lsof -i :8000

# Check what's using port 3000
lsof -i :3000
Stop conflicting services or change ports in docker-compose.yml.
Ensure PostgreSQL is running and accessible:
# Check database container status
docker compose ps db

# View database logs
docker compose logs db

# Connect to database manually
docker compose exec db psql -U open-wearables -d open_wearables
Verify the VITE_API_URL in frontend/.env matches your backend URL. Check for CORS issues in browser console.
Check that Redis is running and the Celery worker is started:
docker compose ps redis celery-worker
docker compose logs celery-worker

​
Next Steps

Now that your environment is set up:
  1. Read the Contributing Guide to understand the development workflow
  2. Review Code Quality Standards before making changes
  3. Explore the Backend Patterns and Frontend Patterns
  4. Try adding a new provider to understand the architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us