Deployment & Configuration

Kinetiqo Installation & Environment Variable Reference

Single source of documentation for deploying Kinetiqo and configuring all supported environment variables.

Quick Start: Docker Compose

Deploy the official lhotakj/kinetiqo:latest image using Docker Compose:

docker-compose.yml

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

volumes:
  kinetiqo_data:

Launch the stack:

docker-compose up -d

Exhaustive Environment Variable Reference

Below is the definitive reference for every environment variable recognized by Kinetiqo, organized by functional area.

1. Strava API Credentials

Variable	Status	Default	Description
STRAVA_CLIENT_ID	REQUIRED	None	Client ID obtained from your Strava API Application Settings.
STRAVA_CLIENT_SECRET	REQUIRED	None	Client Secret from your Strava API Application Settings used for refresh token exchanges.
STRAVA_REFRESH_TOKEN	REQUIRED	None	Initial Strava OAuth Refresh Token with `activity:read_all` and `profile:read_all` scopes (plus `activity:write` if auto-updating Strava descriptions). Rotated tokens are automatically persisted to the database.

2. Security & Web Dashboard Settings

Variable	Status	Default	Description
WEB_LOGIN	OPTIONAL	admin	Username required to log into the Flask web dashboard UI.
WEB_PASSWORD	OPTIONAL	admin123	Password required to log into the Flask web dashboard UI. Recommended to change in production.
SECRET_KEY	RECOMMENDED	Generated at runtime	Long random hex secret used by Flask to sign session cookies and CSRF tokens. Must remain persistent in production to keep user browser sessions valid. Generate with `openssl rand -hex 32`.
KINETIQO_PRODUCTION	OPTIONAL	(empty)	Set to `1` in production environments. Enforces strict security checks (fails server startup if persistent `SECRET_KEY` is missing).
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH	OPTIONAL	Auto-detected	Custom path to system Chromium executable for Playwright poster rendering (e.g. `/usr/bin/chromium` or `/usr/bin/chromium-headless`).

3. Database Connection Settings

Variable	Status	Default	Description
DATABASE_TYPE (or DATABASE)	OPTIONAL	postgresql	Target database backend: `postgresql`, `mysql`, or `firebird`. Can be overridden via CLI `--database-type`.
POSTGRESQL_HOST	IF POSTGRES	localhost	PostgreSQL database server hostname or IP address.
POSTGRESQL_PORT	IF POSTGRES	5432	PostgreSQL database server port.
POSTGRESQL_USER	IF POSTGRES	postgres	PostgreSQL database username.
POSTGRESQL_PASSWORD	IF POSTGRES	None	PostgreSQL database password.
POSTGRESQL_DATABASE	IF POSTGRES	kinetiqo	PostgreSQL database name.
POSTGRESQL_SSL_MODE	IF POSTGRES	disable	PostgreSQL SSL connection mode (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`).
MYSQL_HOST	IF MYSQL	localhost	MySQL / MariaDB database server hostname or IP address.
MYSQL_PORT	IF MYSQL	3306	MySQL / MariaDB database server port.
MYSQL_USER	IF MYSQL	root	MySQL / MariaDB database username. Requires CREATE & ALL PRIVILEGES for schema management.
MYSQL_PASSWORD	IF MYSQL	None	MySQL / MariaDB database password.
MYSQL_DATABASE	IF MYSQL	kinetiqo	MySQL / MariaDB database name.
MYSQL_SSL_MODE	IF MYSQL	disable	MySQL SSL connection mode.
FIREBIRD_HOST	IF FIREBIRD	localhost	Firebird database server hostname.
FIREBIRD_PORT	IF FIREBIRD	3050	Firebird database server port.
FIREBIRD_USER	IF FIREBIRD	firebird	Firebird database username (typically SYSDBA or dedicated user).
FIREBIRD_PASSWORD	IF FIREBIRD	firebird	Firebird database password.
FIREBIRD_DATABASE	IF FIREBIRD	/db/data/kinetiqo.fdb	Firebird database file path or alias. Kinetiqo automatically initializes the database file and schema if not present.

4. Automated Sync Scheduling (dcron Container Engine)

Variable	Status	Default	Description
FAST_SYNC	OPTIONAL	None	Standard 5-field cron expression for incremental fast sync (e.g., `/15 * * *` for every 15 minutes). Fetches only new activities since last sync.
FULL_SYNC	OPTIONAL	None	Standard 5-field cron expression for comprehensive full audit sync (e.g., `0 3 * * *` for daily at 3:00 AM). Reconciles deletions & missing activities.

5. Telemetry, Athlete & Display Settings

Variable	Status	Default	Description
ATHLETE_WEIGHT	OPTIONAL	0.0	Athlete body weight in kilograms (`kg`) for VO₂max Townsend MAP estimation. Primary source is synced Strava profile or Web UI Settings.
DATE_FORMAT	OPTIONAL	%b %d, %Y	Date formatting string for MEGA Stats infographic date headers (e.g., `%b %d, %Y` produces `Aug 07, 2026`).
LOG_LEVEL	OPTIONAL	INFO	Log verbosity for CLI, web app, and Gunicorn process (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).

6. Map Tile Provider API Keys

Variable	Status	Default	Description
MAPY_API_KEY	OPTIONAL	None	API key to enable Mapy.cz outdoor/tourist map tile layer.
THUNDERFOREST_API_KEY	OPTIONAL	None	API key to enable Thunderforest map tile layers (Outdoors, OpenCycleMap, Transport).
MAPTILER_API_KEY	OPTIONAL	None	API key to enable MapTiler vector & satellite map tiles.
GEOAPIFY_API_KEY	OPTIONAL	None	API key to enable Geoapify map tile layers.

7. Strava Auto-Description Templates (`UPDATE_STRAVA_*`)

Define template strings containing any of 150+ placeholders (distance, elevation, ordinals, goals, progress deviations, streak milestones 🎉) to auto-render into Strava descriptions:

Variable	Status	Default	Description
UPDATE_STRAVA_CYCLING_INDOOR	OPTIONAL	(empty)	Description template string applied to indoor cycling activities (Zwift, TrainerRoad, Virtual Ride).
UPDATE_STRAVA_CYCLING_OUTDOOR	OPTIONAL	(empty)	Description template string applied to outdoor cycling activities (Road, Gravel, Mountain Bike).
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 at top) or `end` (appended at bottom).

Annotated Production `.env` Template

Copy and customize this template into a .env file in your Kinetiqo directory:

.env — complete template

# ==========================================
# 1. STRAVA API CREDENTIALS
# ==========================================
STRAVA_CLIENT_ID=12345
STRAVA_CLIENT_SECRET=your_strava_client_secret_here
STRAVA_REFRESH_TOKEN=your_strava_refresh_token_here

# ==========================================
# 2. WEB SECURITY & LOGIN
# ==========================================
WEB_LOGIN=admin
WEB_PASSWORD=admin123
SECRET_KEY=9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e
KINETIQO_PRODUCTION=1

# ==========================================
# 3. DATABASE CONFIGURATION (postgresql / mysql / firebird)
# ==========================================
DATABASE_TYPE=postgresql

# PostgreSQL Settings
POSTGRESQL_HOST=localhost
POSTGRESQL_PORT=5432
POSTGRESQL_USER=postgres
POSTGRESQL_PASSWORD=your_db_password
POSTGRESQL_DATABASE=kinetiqo
POSTGRESQL_SSL_MODE=disable

# MySQL Settings (used if DATABASE_TYPE=mysql)
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_db_password
MYSQL_DATABASE=kinetiqo
MYSQL_SSL_MODE=disable

# Firebird Settings (used if DATABASE_TYPE=firebird)
FIREBIRD_HOST=localhost
FIREBIRD_PORT=3050
FIREBIRD_USER=firebird
FIREBIRD_PASSWORD=firebird
FIREBIRD_DATABASE=/db/data/kinetiqo.fdb

# ==========================================
# 4. AUTOMATED CRON SCHEDULING (dcron)
# ==========================================
FAST_SYNC=*/15 * * * *   # Incremental sync every 15 minutes
FULL_SYNC=0 3 * * *      # Full audit reconciliation daily at 3 AM

# ==========================================
# 5. TELEMETRY, ATHLETE & LOGGING
# ==========================================
ATHLETE_WEIGHT=72.5
DATE_FORMAT=%b %d, %Y
LOG_LEVEL=INFO

# ==========================================
# 6. MAP TILE API KEYS (OPTIONAL)
# ==========================================
MAPY_API_KEY=your_mapy_cz_key
THUNDERFOREST_API_KEY=your_thunderforest_key
MAPTILER_API_KEY=your_maptiler_key
GEOAPIFY_API_KEY=your_geoapify_key

# ==========================================
# 7. STRAVA AUTO-DESCRIPTION TEMPLATES
# ==========================================
UPDATE_STRAVA_CYCLING_OUTDOOR=🚴 Outdoor Ride #{ordinal_cycling_outdoor_year} | 📅 Week {week_number}: {distance_cycling_outdoor_week_km} km ({goal_percent_distance_cycling_outdoor_week} of goal)
UPDATE_STRAVA_CYCLING_INDOOR=🚴 Indoor Session | 🎯 Year Progress: {distance_cycling_indoor_year_km} km
UPDATE_STRAVA_RUNNING_OUTDOOR=🏃 Run #{ordinal_running_outdoor_year} | ⛰️ {elevation_gain_m} m elev
UPDATE_STRAVA_PLACEMENT=end

Need Command-Line Interface Details?

Check out the Click CLI manual for running manual syncs, health checks, and database flags.

View Full CLI Reference →