FitTrack2/FitnessSync/specs/002-fitbit-garmin-sync/quickstart.md

Quickstart: Fitbit/Garmin Data Sync

Date: 2025-12-24

This guide provides instructions on how to set up and run the application to test the Fitbit/Garmin data sync feature.

Prerequisites

• Docker and Docker Compose
• Python 3.11
• An active Garmin Connect account

Setup

1. Clone the repository:

   git clone <repository-url>
   cd <repository-name>
   

2. Set up environment variables:

   • Copy the .env.example file to .env.
   • Fill in the required environment variables, including your Garmin Connect email and password.

   cp .env.example .env
   # Edit .env with your credentials
   

3. Build and run the application:

   docker-compose up --build
   

   The application will be available at http://localhost:8000.

Testing the Endpoints

You can use curl or any API client to test the new endpoints.

1. Trigger Activity Sync

curl -X POST http://localhost:8000/api/sync/activities \
-H "Content-Type: application/json" \
-d '{"days_back": 7}'

2. List Activities

curl http://localhost:8000/api/activities/list

3. Trigger Health Metrics Sync

curl -X POST http://localhost:8000/api/sync/metrics

4. Query Health Metrics

curl "http://localhost:8000/api/metrics/query?metric_type=steps&limit=10"

5. Verify Data in Database

You can connect to the PostgreSQL database to verify that the data has been synced correctly.

docker exec -it <postgres-container-name> psql -U postgres -d fitbit_garmin_sync

Then, run SQL queries to inspect the activities and health_metrics tables:

SELECT * FROM activities;
SELECT * FROM health_metrics;