Deployment & Installation

Deployment & Installation Guide

Deploy Kinetiqo in minutes via Docker CLI or Docker Compose or set up a native Python environment on Linux, macOS, or Windows.

Docker Compose Docker CLI Clone & run Settings

Method 1: Docker Compose (Recommended)

The fastest way to deploy Kinetiqo. Runs on Debian slim with built-in cron sync and container port mapping 4444:4444.

docker-compose.yml

version: '3.8'
services:
  kinetiqo:
    image: lhotakj/kinetiqo:latest
    container_name: kinetiqo
    restart: unless-stopped
    ports:
      - "4444:4444"
    env_file:
      - .env
    volumes:
      - kinetiqo_data:/app/data

volumes:
  kinetiqo_data:

Method 2: Regular Docker CLI

If you prefer running a standalone container without Compose, you can use the standard docker run command. It uses the same environment variables defined in your .env file.

bash

docker run -d \
  --name kinetiqo \
  --restart unless-stopped \
  -p 4444:4444 \
  --env-file .env \
  -v kinetiqo_data:/app/data \
  lhotakj/kinetiqo:latest

Method 3: Clone & run

For those who want to run the application from source code or modify it locally.

bash

# Clone the repository
git clone git@github.com:lhotakj/kinetiqo.git

# Navigate to the project directory
cd kinetiqo

# Install python dependencies (recommended to use venv)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run the Kinetiqo sync or web interface
python src/kinetiqo.py web

Important System Prerequisites

Periodic Sync: Unlike the Docker deployment which uses a built-in cron scheduler, running locally requires you to set up your own periodic sync job (e.g., using system cron or Windows Task Scheduler) calling python src/kinetiqo.py sync.
Firebird Database: If using Firebird, you must manually install the client library (e.g., sudo apt install libfbclient2 on Ubuntu).
Image Export: Playwright requires Chromium to generate posters and infographics. Install it via system packages (apt install chromium) or via Playwright (playwright install chromium-headless-shell).

For a comprehensive list of all available commands, options, and parameters, please refer to the Complete CLI Reference →

Complete Environment Variable Reference (.env)

All configuration variables recognized by Kinetiqo across backend storage, Strava API authentication, decimation, and template engines:

Variable Name	Requirement	Default	Description & Purpose
`DATABASE_TYPE`	REQUIRED	`postgresql`	Database engine backend: `postgresql`, `mysql`, or `firebird`.
`POSTGRESQL_HOST`	REQUIRED	`localhost`	Hostname or IP address of the PostgreSQL database server.
`POSTGRESQL_PORT`	REQUIRED	`5432`	PostgreSQL listener port.
`POSTGRESQL_DATABASE`	REQUIRED	`kinetiqo`	PostgreSQL database name.
`POSTGRESQL_USER`	REQUIRED	`kinetiqo`	PostgreSQL authentication username.
`POSTGRESQL_PASSWORD`	REQUIRED	`(secret)`	PostgreSQL user password.
`MYSQL_HOST`	OPTIONAL	`localhost`	Hostname or IP address of the MySQL/MariaDB server.
`MYSQL_PORT`	OPTIONAL	`3306`	MySQL/MariaDB listener port.
`MYSQL_DATABASE`	OPTIONAL	`kinetiqo`	MySQL database name.
`MYSQL_USER`	OPTIONAL	`kinetiqo`	MySQL authentication username.
`MYSQL_PASSWORD`	OPTIONAL	`(secret)`	MySQL user password.
`FIREBIRD_HOST`	OPTIONAL	`localhost`	Hostname or IP address of the Firebird server.
`FIREBIRD_PORT`	OPTIONAL	`3050`	Firebird listener port.
`FIREBIRD_DATABASE`	OPTIONAL	`/path/to/kinetiqo.fdb`	Firebird database file path or alias.
`FIREBIRD_USER`	OPTIONAL	`SYSDBA`	Firebird authentication username.
`FIREBIRD_PASSWORD`	OPTIONAL	`masterkey`	Firebird user password.
`STRAVA_CLIENT_ID`	REQUIRED	`(from Strava API)`	OAuth 2.0 Client ID from Strava API Application settings.
`STRAVA_CLIENT_SECRET`	REQUIRED	`(secret)`	OAuth 2.0 Client Secret key from Strava API Application settings.
`STRAVA_REFRESH_TOKEN`	REQUIRED	`(token)`	OAuth 2.0 Refresh Token for automatic access token renewal.
`ENABLE_STRAVA_CACHE`	OPTIONAL	`False`	Enable local disk caching for Strava API responses.
`CACHE_TTL`	OPTIONAL	`60`	Strava API cache Time-To-Live in minutes.
`CACHE_DIR`	OPTIONAL	`.cache`	Directory to store Strava API cache files.
`SECRET_KEY`	REQUIRED	`(random 64-hex)`	Flask session encryption key. Must remain persistent across container restarts.
`LOG_LEVEL`	OPTIONAL	`INFO`	Application logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL).
`ATHLETE_WEIGHT`	OPTIONAL	`0.0`	Athlete weight in kilograms. Used for VO₂max estimation.
`DATE_FORMAT`	OPTIONAL	`YYYY-MM-DD`	Global date formatting string for the UI.
`MAPY_API_KEY`	OPTIONAL	`(empty)`	API key for Mapy.cz basemaps (250k credits/mo).
`THUNDERFOREST_API_KEY`	OPTIONAL	`(empty)`	API key for Thunderforest basemaps (150k tiles/mo).
`MAPTILER_API_KEY`	OPTIONAL	`(empty)`	API key for MapTiler basemaps (100k requests/mo).
`GEOAPIFY_API_KEY`	OPTIONAL	`(empty)`	API key for Geoapify basemaps (360k tiles/mo).
`CARTO_API_KEY`	OPTIONAL	`(empty)`	API key for CARTO basemaps (5M requests).
`GPS_SIMPLIFICATION`	OPTIONAL	`3`	Distance-based GPS decimation level (1–10). Level 3 yields 10–30× payload reduction with zero visual distortion on maps.
`WORKOUT_SUMMARY_PEAK_THRESHOLD_W`	OPTIONAL	`300`	Absolute watt floor for sustained peak highlights in the `{{workout-summary}}` placeholder. Effective threshold is max(this, 110% FTP).
`UPDATE_STRAVA_CYCLING_OUTDOOR`	OPTIONAL	`(empty)`	Description template string applied to outdoor cycling activities (Ride, Gravel, Mountain Bike).
`UPDATE_STRAVA_CYCLING_INDOOR`	OPTIONAL	`(empty)`	Description template string applied to indoor trainer activities (VirtualRide).
`UPDATE_STRAVA_RUNNING_INDOOR`	OPTIONAL	`(empty)`	Description template string applied to indoor running activities (Treadmill, Virtual Run).
`UPDATE_STRAVA_RUNNING_OUTDOOR`	OPTIONAL	`(empty)`	Description template string applied to outdoor running & trail running activities.
`UPDATE_STRAVA_WALKING`	OPTIONAL	`(empty)`	Description template string applied to walking & hiking activities.
`UPDATE_STRAVA_SWIMMING`	OPTIONAL	`(empty)`	Description template string applied to pool & open water swimming activities.
`UPDATE_STRAVA_PLACEMENT`	OPTIONAL	`end`	Placement of rendered template block inside Strava description: `begin` (prepended) or `end` (appended).
`DATE_FORMAT`	OPTIONAL	`%b %d, %Y`	Date format string (Python `strftime` syntax) used across the application.