FitTrack_GarminSync/specs/002-intialspecv2/quickstart.md

Quickstart Guide for GarminSync Service

This guide provides instructions to quickly set up and run the GarminSync service.

Prerequisites

• Python 3.13 or newer
• Docker and Docker Compose (version 3.x)
• Git

1. Clone the Repository

First, clone the project repository to your local machine:

git clone https://github.com/your-repo/GarminSync.git
cd GarminSync

2. Set up Python Virtual Environment

It is highly recommended to use a Python virtual environment to manage dependencies.

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure Environment Variables

The service can be configured via environment variables. Create a .env file in the project root based on example.env (if provided) or set them directly in your shell.

Essential Environment Variables:

• GARMIN_CONNECT_EMAIL: Your Garmin Connect account email.
• GARMIN_CONNECT_PASSWORD: Your Garmin Connect account password. (Ensure secure handling of this variable)
• API_PORT: The port the service will listen on (defaults to 8001).

Example .env content:

GARMIN_CONNECT_EMAIL="your_email@example.com"
GARMIN_CONNECT_PASSWORD="your_garmin_password"
API_PORT=8001

4. Run the Service (Development)

You can run the service directly using uvicorn or via Docker Compose.

Option A: Using Uvicorn (for local development)

source .venv/bin/activate
uvicorn src.main:app --host 0.0.0.0 --port ${API_PORT:-8001} --reload

Option B: Using Docker Compose

For a containerized development environment:

docker compose -f docker-compose.dev.yml up --build

5. Access the API Documentation

Once the service is running, you can access the interactive API documentation (Swagger UI) at:

http://localhost:8001/docs (or your configured API_PORT)

6. Basic Usage

Link Garmin Account

To link your Garmin Connect account, send a POST request to /api/garmin/auth/link:

curl -X POST "http://localhost:8001/api/garmin/auth/link" \
     -H "Content-Type: application/json" \
     -d '{
           "email": "your_email@example.com",
           "password": "your_garmin_password"
         }'

Trigger Activity Sync

To trigger activity synchronization:

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

Trigger Health Metrics Sync

To trigger health metrics synchronization:

curl -X POST "http://localhost:8001/api/sync/garmin/health-metrics" \
     -H "Content-Type: application/json" \
     -d '{}'

Upload Workout

To upload a workout (replace <WORKOUT_ID> with an actual workout ID from your CentralDB):

curl -X POST "http://localhost:8001/api/sync/garmin/workouts" \
     -H "Content-Type: application/json" \
     -d '{
           "workout_id": "<WORKOUT_ID>"
         }'

Check Sync Status

To check the status of synchronization jobs:

curl "http://localhost:8001/api/sync/status"

---

Note: This quickstart assumes a basic setup. Refer to the full documentation for advanced configuration, deployment, and troubleshooting.