FitTrack2/FitnessSync/backend/docs/setup.md

Fitbit-Garmin Sync Setup Guide

Prerequisites

Before setting up the Fitbit-Garmin Sync application, ensure you have the following:

• Python 3.11+ installed
• PostgreSQL database server
• Docker and Docker Compose (for containerized deployment)
• Fitbit Developer Account to create an API application
• Garmin Connect Account

Quick Setup with Docker

The easiest way to get started is using Docker Compose:

# Navigate to the backend directory
cd backend

# Start the application and database
docker-compose up --build

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

Manual Setup

1. Clone the Repository

git clone <repository-url>
cd fitbit-garmin-sync

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Database Setup

Create a PostgreSQL database for the application:

createdb fitbit_garmin_sync

5. Environment Configuration

Create a .env file in the backend directory with the following content:

DATABASE_URL=postgresql://username:password@localhost:5432/fitbit_garmin_sync
FITBIT_CLIENT_ID=your_fitbit_client_id
FITBIT_CLIENT_SECRET=your_fitbit_client_secret
FITBIT_REDIRECT_URI=http://localhost:8000/api/setup/fitbit/callback
DEBUG=True

6. Run the Application

# Using uvicorn directly
uvicorn main:app --host 0.0.0.0 --port 8000

Configuration Steps

Once the application is running, you'll need to configure both Fitbit and Garmin access:

1. Garmin Connect Setup

1. Navigate to the Setup page at http://localhost:8000/setup
2. Enter your Garmin Connect username and password
3. Click "Save Garmin Credentials"

2. Fitbit API Setup

1. Go to the Fitbit Developer Portal
2. Create a new application
3. Set the OAuth 2.0 Application Type to "Personal"
4. Set the Callback URL to http://localhost:8000/api/setup/fitbit/callback
5. Note down the "Client ID" and "Client Secret"
6. On the setup page, enter these values in the Fitbit API Credentials section
7. Click "Save Fitbit Credentials"
8. Click the authorization link that appears to connect your Fitbit account
9. After authorizing, copy the complete URL from your browser and paste it in the "Complete Fitbit OAuth Flow" section
10. Click "Complete OAuth Flow"

Running the Synchronization

1. Weight Sync

1. Go to the home page (/)
2. Click the "Sync Weight" button
3. Monitor the sync status in the logs table

2. Activity Archiving

1. Go to the home page (/)
2. Click the "Sync Activities" button
3. Enter the number of days back to look for activities
4. The original activity files (.fit, .gpx, .tcx) will be downloaded from Garmin and stored in the PostgreSQL database
5. Monitor the sync status in the logs table
6. Use the "List Stored Activities" and "Download Activity File" options to access stored activity files

3. Health Metrics Sync

1. Go to the home page (/)
2. Click the "Sync Health Metrics" button
3. Monitor the sync status in the logs table

Security Considerations

• Store API credentials securely (not in version control)
• Use environment variables for configuration
• Encrypt sensitive data stored in the database
• Regularly rotate API tokens
• Implement proper error handling to avoid information disclosure

Troubleshooting

Common Issues

• Database Connection: Ensure PostgreSQL is running and accessible
• API Credentials: Verify Fitbit and Garmin credentials are correct
• Rate Limits: Be mindful of API rate limits from both providers
• Network Issues: Ensure the application has internet access

Logs

Check the application logs for errors:

# In Docker
docker-compose logs app

# For direct Python execution, add logging to track operations

Updating

To update to the latest version:

# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt

# Restart the application