Live Trail is a self-hosted web application for sharing journeys on an interactive map. It combines live GPS positions from a SPOT tracker with GPX routes, posts, photos, videos, and a chronological activity feed, supporting both real-time tracking and historical travel stories.

Dependencies

npm 24+
composer
php-mbstring
php-imagick
php-gd
php-mysql
php-exif
ffprobe & ffmpeg
STARTTLS Email Server (use Gmail if none available)
Optional: Geo Caching Server (WMTS Caching Service)

PHP Configuration

max_execution_time = 300
memory_limit = 500M
post_max_size = 4G
upload_max_filesize = 4G
max_file_uploads = 50

Getting started

Clone Git onto web server
Update php.ini parameters
Copy timezone data: mariadb-tzinfo-to-sql /usr/share/zoneinfo | mariadb -u root mysql
Copy settings-sample.php to settings.php and populate
Follow CI/CD script in .gitea/workflows/deploy.yml
Add a GPX file named <project_codename>.gpx to /resources/geo/
Go to #admin and create a new project (with code name = <project_codename>) & feed

Web Root

The web server should serve public/ as the application document root. PHP source, configuration, Composer dependencies, uploaded files, and GPX data stay outside the public tree; public/index.php is the front controller and Vite writes generated frontend assets to public/assets/.

Runtime data is exposed through symlinks only: public/files -> ../files and public/geo -> ../resources/geo. The build must not copy uploaded media or GPX data into public/.

Local Development

npm run dev watches and builds development assets into public/assets/. npm run prod builds hashed production assets into public/assets/. PHP reads public/.vite/manifest.json and populates the CSS, module, and preload parts defined in resources/masks/index.html while rendering the request.

When developing Livetrail and the sibling objects library together, install dependencies through the local Composer manifest:

COMPOSER=composer.dev.json composer update

This makes Composer link vendor/franzz/objects to ../objects and autoload that namespace directly from the local source path. Production continues to use composer.json, which installs franzz/objects from its Git repository. Commit and publish objects changes before updating/deploying a Livetrail version that relies on them.

Before Committing

Run manually before pushing:

composer lint - checks PHP style (php-cs-fixer, dry-run); composer lint-fix applies it. Requires the dev dependencies (COMPOSER=composer.dev.json composer update, see Local Development above).
npm run lint - checks JS/Vue style (ESLint) on demand. It also already runs automatically as part of npm run dev (reports issues but never blocks the watcher) and npm run prod (aborts the build if any lint error is found).

To Do List

Add mail frequency slider
Use WMTS servers directly when not using Geo Caching Server
Allow HEIF picture format
Garmin InReach Integration