FitTrack_GarminSync/quickstart.md

Quickstart Guide: GarminSync Service

This guide provides essential steps for setting up and running the GarminSync service.

1. Prerequisites

Before you begin, ensure you have the following installed:

• Docker and Docker Compose: The service is containerized using Docker. Ensure Docker Engine and Docker Compose V3 are installed on your system.
  • Install Docker
  • Install Docker Compose
• Python 3.13+: While the service runs in Docker, you might need Python for local development tools or scripting.
  • Install Python
• Git: For cloning the repository.

2. Environment Setup

2.1. Clone the Repository

First, clone the GarminSync service repository:

git clone <repository-url>
cd <repository-name>

2.2. Create and Activate a Python Virtual Environment (Optional, for local development)

It's recommended to use a virtual environment for dependency management:

python3.13 -m venv .venv
source .venv/bin/activate

2.3. Install Dependencies (Optional, for local development)

If you are developing locally outside of Docker, install the Python dependencies:

pip install -r requirements.txt
pip install -r requirements-dev.txt

3. Configuration

The GarminSync service can be configured via YAML files or environment variables.

3.1. Default Configuration

The service defaults to listening on port 8001.

3.2. CentralDB Integration

The service requires a running CentralDB instance. By default, it expects CentralDB to be accessible via its API. The DB_API_SPEC.json defines the CentralDB API, and the service will attempt to refresh this spec from http://localhost:8000/openapi.json.

You will likely need to configure the CentralDB connection details, either in a YAML configuration file or via environment variables. Refer to the project's main README.md or config directory for specific configuration options.

4. Running the Service

The recommended way to run the GarminSync service is using Docker Compose.

4.1. Development Environment

To run the service in a development environment:

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

This command will build the necessary Docker images and start the GarminSync service along with any other services defined in docker-compose.dev.yml (e.g., CentralDB, Redis).

4.2. Production Environment

To run the service in a production environment (typically in detached mode):

docker compose -f docker-compose.prod.yml up -d

4.3. Accessing the Service

Once the service is running, it will be accessible at http://localhost:8001 (or the configured port). You can then interact with its API endpoints.

5. Basic Usage

5.1. Link Garmin Connect Account

Before syncing data, you need to link your Garmin Connect account:

curl -X POST http://localhost:8001/api/garmin/auth/link \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "email": "your_garmin_email@example.com",
           "password": "your_garmin_password"
         }'

Replace <your-app-auth-token>, your_garmin_email@example.com, and your_garmin_password with your actual authentication token and Garmin Connect credentials.

Note on Authentication: Currently, <your-app-auth-token> is a placeholder. Any non-empty string will be accepted as a valid token by the backend's authentication mechanism, which will then return a mock user. Full token management will be implemented in a future update.

5.2. Trigger Activity Synchronization

To trigger an activity sync:

curl -X POST http://localhost:8001/api/sync/garmin/activities \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "start_date": "2024-01-01",
           "end_date": "2024-01-31"
         }'

5.3. Check Sync Status

To check the status of synchronization processes:

curl -X GET http://localhost:8001/api/sync/status \
     -H "Authorization: Bearer <your-app-auth-token>"

5.4. Upload a Workout

To upload a workout (assuming you have a workout defined in CentralDB with ID [workout_id]):

curl -X POST http://localhost:8001/api/sync/garmin/workouts \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-app-auth-token>" \
     -d '{
           "workout_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
         }'

6. Next Steps

• Refer to the full API documentation (available via OpenAPI/Swagger at /docs or /redoc when the service is running) for all available endpoints and detailed usage.
• Explore the tests/ directory for examples of how to interact with the service.
• Consult the constitution.yaml for development and code quality standards.