mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 08:35:23 +00:00
129 lines
3.1 KiB
Markdown
129 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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. |