Skip to content

Commit cbba2d5

Browse files
seanapseanap
committed
Add sources setup doc
1 parent 8aa7e95 commit cbba2d5

1 file changed

Lines changed: 160 additions & 0 deletions

File tree

‎docs/SOURCES_SETUP.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Sources Setup Guide
2+
3+
This guide walks you through getting your credentials and connecting each source from the Chronicle `Sources` page:
4+
- `http://localhost:1609/setup`
5+
6+
## Before You Start
7+
- Chronicle is running (`docker compose up -d`).
8+
- You can open `http://localhost:1609/setup` in your browser.
9+
- You only need to configure the sources you actually use.
10+
11+
---
12+
13+
## Step 1: Open Sources Page
14+
1. Open `http://localhost:1609/setup`.
15+
2. You will see provider cards (Strava, Garmin, Intervals, Weather, Smashrun, Crono, etc.).
16+
17+
<img width="2336" height="1939" alt="Screenshot 2026-02-20 115752 REDACTED" src="https://github.com/user-attachments/assets/b2d7056b-6dae-4c94-b3be-2ddda7a51155" />
18+
19+
---
20+
21+
## Step 2: Strava (Required)
22+
1. Open Strava api settings: https://www.strava.com/settings/api
23+
2. Create `My API Application`
24+
3. Fill app fields:
25+
- Application Name: anything (ex: Chronicle)
26+
- Category: any relevant category
27+
- Website: for local setup, http://localhost is fine
28+
- Authorization Callback Domain: this is the important one (host only)
29+
<img width="1085" height="1156" alt="Screenshot 2026-02-20 122551 Highlighted" src="https://github.com/user-attachments/assets/a96a0d94-e466-44e2-b8d0-7cdfb19b38ee" />
30+
31+
4. Set callback domain based on how you open Chronicle:
32+
- If you use http://localhost:1609/setup -> set callback domain to localhost
33+
5. Copy your `CLIENT_ID` and `CLIENT_SECRET`
34+
35+
<img width="1298" height="1884" alt="Screenshot 2026-02-20 121252 REDACTED" src="https://github.com/user-attachments/assets/e667fb1c-4922-41d4-9ad3-3a74f8cf327e" />
36+
37+
6. Go to Chronicle Sources `/setup` page:
38+
* Enter `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET`.
39+
* Click **Save Setup**.
40+
* Click **Connect Strava OAuth** inside the Strava card.
41+
* Approve access on Strava.
42+
* You should be redirected back to /setup as connected
43+
44+
<img width="705" height="939" alt="Screenshot 2026-02-20 123909 Highlighted" src="https://github.com/user-attachments/assets/f5a13bfa-da5b-462a-81e7-0de4c4f19121" />
45+
46+
47+
Common issues:
48+
- OAuth start fails: client id/secret not saved yet.
49+
- Callback mismatch: verify your Strava app callback settings.
50+
51+
---
52+
53+
## Step 3: Garmin (Optional)
54+
Where to get it:
55+
- Your regular Garmin Connect account: https://connect.garmin.com/
56+
57+
Fields in `Sources`:
58+
- `ENABLE_GARMIN` (toggle)
59+
- `GARMIN_EMAIL`
60+
- `GARMIN_PASSWORD`
61+
62+
Steps:
63+
1. Enable Garmin toggle.
64+
2. Enter your Garmin login email and password.
65+
3. Save setup.
66+
67+
---
68+
69+
## Step 4: Intervals.icu (Optional)
70+
Where to get it:
71+
- Intervals: https://intervals.icu/
72+
- API key and user id are in your Intervals account settings.
73+
74+
Fields in `Sources`:
75+
- `ENABLE_INTERVALS` (toggle)
76+
- `INTERVALS_API_KEY`
77+
- `INTERVALS_USER_ID`
78+
79+
Steps:
80+
1. Enable Intervals toggle.
81+
2. Paste API key and user ID.
82+
3. Save setup.
83+
84+
---
85+
86+
## Step 5: WeatherAPI (Optional)
87+
Where to get it:
88+
- Sign up and create a key: https://www.weatherapi.com/signup.aspx
89+
90+
Fields in `Sources`:
91+
- `ENABLE_WEATHER` (toggle)
92+
- `WEATHER_API_KEY`
93+
94+
Steps:
95+
1. Enable Weather toggle.
96+
2. Paste your WeatherAPI key.
97+
3. Save setup.
98+
99+
---
100+
101+
## Step 6: Smashrun (Optional)
102+
Where to get it:
103+
- Smashrun API docs: https://api.smashrun.com/v1/documentation
104+
105+
Fields in `Sources`:
106+
- `ENABLE_SMASHRUN` (toggle)
107+
- `SMASHRUN_ACCESS_TOKEN`
108+
109+
Steps:
110+
1. Enable Smashrun toggle.
111+
2. Paste access token.
112+
3. Save setup.
113+
114+
---
115+
116+
## Step 7: Crono API (Optional)
117+
Where to get it:
118+
- Project reference: https://github.com/seanap/crono-api
119+
120+
Fields in `Sources`:
121+
- `ENABLE_CRONO_API` (toggle)
122+
- `CRONO_API_BASE_URL` (example: `http://<your-ip>:8777`)
123+
- `CRONO_API_KEY` (Only if your instance requires one)
124+
125+
Steps:
126+
1. Enable Crono API toggle.
127+
2. Enter base URL (and API key if required).
128+
3. Save setup.
129+
130+
---
131+
132+
## Step 8: Timezone (General)
133+
Field in `Sources`:
134+
- `TIMEZONE`
135+
136+
Use an IANA timezone value. Examples:
137+
- `America/Los_Angeles`
138+
- `America/Denver`
139+
- `America/Chicago`
140+
- `America/New_York`
141+
142+
---
143+
144+
## Step 9: Save and Verify
145+
1. Click **Save Setup**.
146+
2. Click **Reload**.
147+
3. Verify status chips/messages are healthy.
148+
4. Optional verification endpoints:
149+
```bash
150+
curl http://localhost:1609/health
151+
curl http://localhost:1609/ready
152+
curl http://localhost:1609/setup/api/config
153+
```
154+
155+
156+
---
157+
158+
## What Gets Saved
159+
- `.env` is the canonical saved config. If changing `.env` manually you will need to restart the container.
160+
- Chronicle also writes runtime setup overrides so `.env` changes apply immediately without a restart when using the `/setup`

0 commit comments

Comments
 (0)