From b25fc91894b6f909218c45ffc4bc4bc0db4cd455 Mon Sep 17 00:00:00 2001
From: Maksym Buz <buz.maxim@gmail.com>
Date: Wed, 24 Dec 2025 15:23:40 +0100
Subject: [PATCH] Change: README and slight compose changes

---
 garmin-grafana/README.md           | 29 ++++++++++++++++++++++++-----
 garmin-grafana/docker-compose.yaml | 13 ++++++++++---
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/garmin-grafana/README.md b/garmin-grafana/README.md
index c929dc7..d47ba5a 100644
--- a/garmin-grafana/README.md
+++ b/garmin-grafana/README.md
@@ -11,14 +11,33 @@ This directory contains the configuration for a set of services that fetches dat
 ## How to start
 
 1.  Create a `.env` file based on the `.env.example` file.
-2.  Set the `GARMINCONNECT_EMAIL` and `GARMINCONNECT_PASSWORD` variables in the `.env` file.
-3.  Run `docker-compose up -d` to start the application.
+2.  Set the `GARMINCONNECT_EMAIL` and `GARMINCONNECT_PASSWORD` (Base64 encoded) variables in the `.env` file.
+3.  **If you have 2FA enabled:** You must authenticate manually once to generate the session tokens.
+    ```bash
+    docker-compose run --rm garmin-fetch-data
+    ```
+    Enter your 2FA code when prompted. The tokens will be saved to the `garminconnect_tokens` volume.
+4.  Run `docker-compose up -d` to start the application.
 
-## Setup
+## Setup & Access
 
-After starting the application, you can access the Grafana web interface at [http://localhost:3000](http://localhost:3000) and log in with the default credentials:
+After starting the application, you can access the Grafana web interface at [http://localhost:3000](http://localhost:3000).
 
 -   **User**: `admin`
 -   **Password**: `admin`
 
-You can then configure a new data source for InfluxDB and create dashboards to visualize your Garmin Connect data.
\ No newline at end of file
+Configure a new data source for InfluxDB (URL: `http://influxdb:8086`, Database: `GarminStats`) and import the dashboards.
+
+## Historical Data Download (Bulk Import)
+
+To download old history, use the `MANUAL_START_DATE` variable. This will fetch data in reverse chronological order from the current date (or `MANUAL_END_DATE`) back to the start date.
+
+```bash
+docker-compose run --rm -e MANUAL_START_DATE=YYYY-MM-DD garmin-fetch-data
+```
+
+**Options:**
+-   `MANUAL_END_DATE=YYYY-MM-DD`: Optional end date (defaults to today).
+-   `FETCH_SELECTION=...`: Limit what data is fetched (e.g., `activity,sleep`).
+
+*Note: Garmin archives intraday data older than 6 months, so very old detailed data (HR, sleep stages) might be missing unless manually refreshed in the Garmin Connect app.*
\ No newline at end of file
diff --git a/garmin-grafana/docker-compose.yaml b/garmin-grafana/docker-compose.yaml
index 8db4851..db2205a 100644
--- a/garmin-grafana/docker-compose.yaml
+++ b/garmin-grafana/docker-compose.yaml
@@ -18,6 +18,13 @@ services:
       - LOG_LEVEL=INFO
       - GARMINCONNECT_EMAIL=${GARMINCONNECT_EMAIL}
       - GARMINCONNECT_BASE64_PASSWORD=${GARMINCONNECT_PASSWORD} # (must be base64 encoded)
+      - GARMINCONNECT_IS_CN=False
+      # - USER_TIMEZONE=Europe/Paris # Optional: Override automatic timezone detection
+      # - FETCH_SELECTION=daily_avg,sleep,steps,heartrate,stress # Optional: Select specific data to fetch
+      # - KEEP_FIT_FILES=False
+      # - ALWAYS_PROCESS_FIT_FILES=False
+      # - MANUAL_START_DATE=2023-01-01 # For bulk import: set date and run with docker-compose run ...
+      # - MANUAL_END_DATE=2023-01-31   # For bulk import: defaults to today if unset
     networks:
       - garmin-grafana-net
 
@@ -34,9 +41,9 @@ services:
     ports:
       - '8086:8086'
     volumes:
-     - influxdb_data:/var/lib/influxdb
+      - influxdb_data:/var/lib/influxdb
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8086/ping"]
+      test: [ "CMD", "curl", "-f", "http://localhost:8086/ping" ]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -56,7 +63,7 @@ services:
     ports:
       - '3000:3000'
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
+      test: [ "CMD", "curl", "-f", "http://localhost:3000/api/health" ]
       interval: 10s
       timeout: 5s
       retries: 5