162 lines
4.0 KiB
Markdown
162 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd fitbit-garmin-sync
|
|
```
|
|
|
|
### 2. Create Virtual Environment
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 4. Database Setup
|
|
|
|
Create a PostgreSQL database for the application:
|
|
|
|
```bash
|
|
createdb fitbit_garmin_sync
|
|
```
|
|
|
|
### 5. Environment Configuration
|
|
|
|
Create a `.env` file in the backend directory with the following content:
|
|
|
|
```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
|
|
DEBUG=True
|
|
```
|
|
|
|
### 6. Run the Application
|
|
|
|
```bash
|
|
# 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](https://dev.fitbit.com/)
|
|
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:
|
|
|
|
```bash
|
|
# In Docker
|
|
docker-compose logs app
|
|
|
|
# For direct Python execution, add logging to track operations
|
|
```
|
|
|
|
## Updating
|
|
|
|
To update to the latest version:
|
|
|
|
```bash
|
|
# Pull latest changes
|
|
git pull origin main
|
|
|
|
# Update dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Restart the application
|
|
``` |