109 lines
2.9 KiB
Markdown
109 lines
2.9 KiB
Markdown
# Quickstart Guide: Fitbit-Garmin Local Sync
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.11+
|
|
- PostgreSQL database
|
|
- Docker and Docker Compose (for containerized deployment)
|
|
- Fitbit Developer Account (to create an app and get API credentials)
|
|
- Garmin Connect Account
|
|
|
|
## Setup
|
|
|
|
### 1. Clone and Install Dependencies
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd fitbit-garmin-sync
|
|
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Database Setup
|
|
|
|
```bash
|
|
# Create PostgreSQL database
|
|
createdb fitbit_garmin_sync
|
|
|
|
# Update database configuration in application
|
|
# The application will handle schema creation automatically
|
|
```
|
|
|
|
### 3. Environment Configuration
|
|
|
|
Create a `.env` file with the following:
|
|
|
|
```env
|
|
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
|
|
```
|
|
|
|
### 4. Run the Application
|
|
|
|
```bash
|
|
# Using uvicorn directly
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
|
|
# Or using Docker
|
|
docker-compose up --build
|
|
```
|
|
|
|
## Initial Configuration
|
|
|
|
1. Open the application in your browser at `http://localhost:8000`
|
|
2. Navigate to the Setup page (`/setup`)
|
|
3. Enter your Garmin Connect username and password
|
|
4. Enter your Fitbit Client ID and Client Secret
|
|
5. Click the authorization link provided to authenticate with Fitbit
|
|
6. Copy the full callback URL from your browser after authorizing and paste it into the input field on the setup page
|
|
|
|
## Using the Application
|
|
|
|
### Sync Weight Data
|
|
|
|
1. Go to the home page (`/`)
|
|
2. Click the "Sync Weight" button
|
|
3. Monitor the sync status in the logs table
|
|
|
|
### Archive Activities
|
|
|
|
1. Go to the home page (`/`)
|
|
2. Click the "Sync Activities" button
|
|
3. Enter the number of days back to look for activities
|
|
4. Monitor the sync status in the logs table
|
|
|
|
### View Health Metrics
|
|
|
|
1. Use the API endpoints to query health metrics:
|
|
- `/api/metrics/list` - List available metric types
|
|
- `/api/metrics/query` - Query specific metrics
|
|
- `/api/health-data/summary` - Get aggregated health statistics
|
|
|
|
## Docker Deployment
|
|
|
|
```bash
|
|
# Build and run with Docker Compose
|
|
docker-compose up --build
|
|
|
|
# The application will be available at http://localhost:8000
|
|
# PostgreSQL database will be automatically set up
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
See the full API documentation in the `contracts/api-contract.yaml` file or access the automatic documentation at `/docs` when running the application.
|
|
|
|
## Multi-Factor Authentication (MFA) Support
|
|
|
|
The application handles Garmin's MFA flow automatically:
|
|
1. When prompted for MFA, enter your Garmin credentials on the setup page
|
|
2. If MFA is required, you'll receive a code via SMS or email
|
|
3. Enter the code on the MFA verification page to complete authentication |