RunTracker

A family running activity tracker web application that allows you to upload GPX/TCX files, track multiple runners, visualize routes on maps, generate heatmaps, and view dashboard statistics.

Features

• Runner Management: Create and manage multiple runners
• Activity Upload: Upload GPX/TCX files with automatic parsing of distance, duration, pace, and elevation
• Activity Tracking: View all activities with detailed metrics
• Interactive Maps: Visualize running routes on OpenStreetMap
• Heatmap: See all running routes overlaid on a single map
• Dashboard: View statistics including:
  • Activity counts (last week, month, year)
  • Total distances
  • Top runners by mileage
  • Activity calendar with 4-week view
• Filtering: Filter activities and stats by specific runners

Tech Stack

Backend

• Node.js + Express
• TypeScript
• SQLite (better-sqlite3)
• Multer (file uploads)
• GPX/TCX parsing

Frontend

• React + TypeScript
• Vite
• React Router
• Leaflet.js (maps)
• Recharts (optional for future charts)

Deployment

• Docker + Docker Compose
• Nginx (frontend)

Prerequisites

• Docker and Docker Compose installed
• OR Node.js 22+ (for local development)

Quick Start with Docker

1. Clone the repository:

cd RunTracker

2. Start the application:

docker-compose up -d

3. Access the application:

• Frontend: http://localhost:8080
• Backend API: http://localhost:3000

4. Stop the application:

docker-compose down

Local Development Setup

Backend

1. Navigate to backend directory:

cd backend

2. Install dependencies:

npm install

3. Create a .env file (copy from .env.example):

cp .env.example .env

4. Start the development server:

npm run dev

The backend will run on http://localhost:3000

Frontend

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will run on http://localhost:5173

Usage Guide

1. Add Runners

1. Navigate to the "Runners" page
2. Fill in the username and display name
3. Click "Add Runner"

2. Upload an Activity

1. Navigate to the "Upload Activity" page
2. Enter an activity title
3. Select a GPX or TCX file
4. Select one or more runners who participated
5. Click "Upload Activity"

3. View Activities

1. Navigate to the "Activities" page
2. Click on any activity to view details
3. Use the runner filter to show activities for specific runners

4. View Heatmap

1. Navigate to the "Heatmap" page
2. See all routes overlaid on a single map
3. Use the runner filter to show routes for specific runners

5. View Dashboard

1. Navigate to the "Dashboard" page (or home)
2. View recent activities, statistics, and calendar
3. Use the runner filter for personalized stats

File Upload Limits

The application supports uploading GPX/TCX files up to 20MB in size. This limit is configured in:

• Nginx: client_max_body_size 20M
• Backend: Multer file size limit of 20MB
• Express: Body parser limit of 20MB

If you need to upload larger files, adjust these settings:

1. frontend/nginx.conf - Increase client_max_body_size
2. backend/src/middleware/upload.ts - Increase fileSize limit
3. backend/src/index.ts - Increase limit in express.json() and express.urlencoded()
4. Rebuild Docker containers: docker-compose up --build

Data Backup

To backup your data, simply copy the ./data directory:

cp -r data data-backup-$(date +%Y%m%d)

To restore, replace the ./data directory with your backup.

Development

Backend Development

Run TypeScript compiler in watch mode:

npm run dev

Build for production:

npm run build
npm start

Frontend Development

Start development server with hot reload:

npm run dev

Build for production:

npm run build
npm run preview

Contributing

This is a personal/family project, but feel free to fork and customize for your needs!

License

MIT

Support

For issues or questions, please open an issue on GitHub.