# Jog Japan — Progress Tracker

> **Status:** Active
> **Category:** Web Apps
> **Language:** Python 3 (Flask)
> **Script file:** `app.py`

## Purpose

A Flask web application for tracking jogging progress along a geospatial route through Japan (Shimonoseki to Aomori). As kilometres are logged, your current position is interpolated on a live map. Push notifications are sent via ntfy.sh when a new jog entry or comment is posted.

## Requirements

### Dependencies

```bash
pip install flask flask-sqlalchemy geopy requests
```

Or with Docker (recommended):

```bash
docker-compose up -d
```

## Input

| Item | Description | Example |
|------|-------------|---------|
| Jog distance | Distance in km for a single session | `5.2` |
| Jog date | Date of the jog session | `2026-05-01` |
| Comment (optional) | Free-text note with an author name | `"Good run today"` |

Admin credentials and ntfy settings are configured via environment variables (see Notes).

## Output

| Item | Description |
|------|-------------|
| Web dashboard | Progress bar, interactive map, nearby city info, combined activity feed |
| Admin panel | Table of all jog entries and comments with delete controls |
| Push notification | Sent to configured ntfy.sh topic on new jog entry or comment |
| SQLite database | `jogdata.db` auto-created on first run, persists all data |

## Routes

| Route | Description |
|-------|-------------|
| `/` | Main progress page — map, stats, recent activity feed |
| `/admin` | Admin panel — add/delete jog entries and comments (login required) |
| `/login` | Admin login form |
| `/logout` | End admin session |
| `/comment` | POST endpoint for submitting a comment |
| `/admin/delete_jog/<id>` | DELETE a jog entry (POST, admin only) |
| `/admin/delete_comment/<id>` | DELETE a comment (POST, admin only) |

## Usage

### Running directly

```bash
pip install flask flask-sqlalchemy geopy requests
python app.py
```

Open `http://localhost:5000` in your browser.

### Running with Docker

```bash
docker-compose up -d
```

The `docker-compose.yml` and `Dockerfile` are included in the project.

## Examples

```bash
# Start the app locally
python app.py

# Start with custom admin password and ntfy topic
ADMIN_PASS=mypassword NTFY_TOPIC=myjog python app.py

# Docker with environment overrides
ADMIN_PASS=mypassword NTFY_TOPIC=myjog docker-compose up -d
```

## Route Data

The `route_data.py` module defines 12 waypoints covering the full route:

**Shimonoseki → Hiroshima → Okayama → Osaka → Nagoya → Shizuoka → Tokyo → Yokohama → Utsunomiya → Sendai → Morioka → Aomori**

Geospatial interpolation via `geopy` calculates the exact lat/lon position between waypoints based on total km logged. Each city has associated local food, landmarks, and famous people displayed on the dashboard.

## Database Models

| Model | Fields |
|-------|--------|
| `Jog` | `id`, `distance` (km, float), `date`, `created_at` |
| `Comment` | `id`, `author`, `content` (max 200 chars), `created_at` |

The SQLite database file `jogdata.db` is created automatically inside a `instance/` folder on first run.

## Notes

- **Admin password:** Set via `ADMIN_PASS` environment variable. Defaults to `secret123` — change this before deploying.
- **Flask secret key:** Set via `FLASK_SECRET` environment variable. Defaults to `fallback_secret_key` — change before deploying.
- **ntfy.sh notifications:** Requires `NTFY_TOPIC` environment variable. If `NTFY_TOKEN` is set and does not contain the placeholder string `paste_your_token`, it is sent as a Bearer token. Notifications are silently skipped if `NTFY_TOPIC` is unset or contains `change_me`.
- **ntfy base URL:** Defaults to `https://ntfy.sh` but can be overridden with `NTFY_BASE_URL` for self-hosted instances.
- The app runs in debug mode (`debug=True`) when launched directly — disable this in production.
- Total route distance and all position calculations are driven by `route_data.py`; edit that file to change waypoints or distances.

## Related Scripts

- [VGMdb Collection Scraper (Docker)](docker-vgmdb-scraper.md) — another Flask web app with Docker support in this collection