Installation¶

The following steps describe an installation on Linux systems (tested with ArchLinux-based OS and Ubuntu on CI).

On other operating systems, some issues can be encountered and adaptations may be necessary.

Note

Other installation guides are available thanks to contributors:

Installation on Uberspace Web hosting (Fittrackee 0.7.25)
Installation on Debian 12 net install (guide in German) (Fittrackee 0.7.31)

Warning

Note that FitTrackee is under heavy development, some features may be unstable.

Note

Depending on the operating system and the version of Python installed, additional dependencies may be required, such as gcc or libgdal-dev.

From PyPI¶

Create and activate a virtualenv
Install FitTrackee with pip

$ pip install fittrackee

Create fittrackee database

Example:

CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
CREATE SCHEMA fittrackee AUTHORIZATION fittrackee;
CREATE DATABASE fittrackee OWNER fittrackee;

Note

see PostgreSQL documentation for schema and privileges.

Install PostGIS extension

Example for fittrackee database:

$ psql -U <SUPER_USER> -d fittrackee -c 'CREATE EXTENSION IF NOT EXISTS postgis;'

Note

PostGIS must be installed on OS, see installation documentation.

Many OS includes pre-built packages for PostGIS, see wiki.

Initialize environment variables, see Environment variables

For instance, copy and update .env file from .env.example and source the file.

$ nano .env
$ source .env

Initialize database schema

$ ftcli db upgrade

Start the application

$ fittrackee

Start task queue workers if email sending is enabled, with Dramatiq CLI (see documentation) :

$ dramatiq fittrackee.tasks:broker --processes=$WORKERS_PROCESSES --log-file=$DRAMATIQ_LOG

Note

It is also possible to start task queue workers with Flask-Dramatiq CLI:

$ flask worker --processes 2

But running Flask-Dramatiq CLI on Python 3.13+ raises errors. Emails and user data export are sent, but the middleware preventing actors from running too long is not active. Please use Dramatiq CLI instead for now.

Note

To start application and workers with systemd service, see Deployment.

Open http://localhost:5000 and register
To set owner role to the newly created account, use the following command line:

$ ftcli users update <username> --set-role owner

Note

If the user account is inactive, it activates it.

From sources¶

Warning

Since FitTrackee 0.2.1, Python packages installation needs Poetry.

For more information, see Poetry Documentation

Note

To keep virtualenv in project directory, update Poetry configuration.

$ poetry config virtualenvs.in-project true

Production environment¶

Warning

Note that FitTrackee is under heavy development, some features may be unstable.

Download the last release (for now, it is the release v1.1.0):

$ wget https://github.com/SamR1/FitTrackee/archive/1.1.0.tar.gz
$ tar -xzf v1.1.0.tar.gz
$ mv FitTrackee-1.1.0 FitTrackee
$ cd FitTrackee

Create .env from example and update it (see Environment variables).
Install Python virtualenv and all related packages:

$ make install-python

Initialize the database (after updating db/create.sql to change database credentials):

$ make install-db

Start the server and Dramatiq workers:

$ make run

Note

If email sending is disabled: $ make run-server

Open http://localhost:5000 and register
To set owner role to the newly created account, use the following command line:

$ make user-set-role USERNAME=<username> ROLE=owner

Note

If the user account is inactive, it activates it.

Dev environment¶

Clone this repo:

$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee

Create .env from example and update it (see Environment variables).
Install Python virtualenv, Vue and all related packages and initialize the database:

$ make install-dev
$ make install-db-dev

Start the server and the client:

$ make serve

Run Dramatiq workers:

$ make run-workers

Open http://localhost:3000 and register
To set owner role to the newly created account, use the following command line:

$ make user-set-role USERNAME=<username> ROLE=owner

Note

If the user account is inactive, it activates it.

Docker¶

Added in version 0.4.4.

Changed in version 0.5.0: add client application for development

Changed in version 0.8.13: add docker image for production

Production¶

Images are available on DockerHub or Github registry.

Note

Images are available for linux/amd64 and linux/arm64 platforms. Only linux/amd64 image has been tested.

Warning

There is no official image for PostGIS on ARM platforms yet, see issue on GitHub.

The workaround is to build PostGIS image locally.

create a docker-compose.yml file as needed (see the example in the repository):
- the minimal set up requires at least the database and the web application
- to activate the rate limit, redis is required
- to send e-mails, redis and workers are required and a valid EMAIL_URL variable must be set in .env

Note

The same image is used by the web application and workers.

Warning

Following directory must be writable for fittrackee user (see docker-compose.yml example):

/usr/src/app/uploads
/usr/src/app/logs
/usr/src/app/.staticmap_cache

create .env from example (.env.docker.example) and update it (see Environment variables).
to start the application:

$ docker compose up -d

Warning

Migrations are executed at startup. Please backup data before updating FitTrackee image version.

to run a CLI command, for instance to give admin rights:

$ docker compose exec fittrackee ftcli users update <username> --set-role admin

Development¶

To install and run FitTrackee:

$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
$ make docker-run

Open http://localhost:5000 and register.

Note

To change fittrackee container port when running containers with Makefile commands, create a .env file with HOST_APP_PORT.

For example:

export HOST_APP_PORT=5001

Open http://localhost:8025 to access MailHog interface (email testing tool)

To set owner role to the newly created account, use the following command line:

$ make docker-set-role USERNAME=<username> ROLE=owner

Note

If the user account is inactive, it activates it.

To stop Fittrackee:

$ make docker-stop

To run shell inside Fittrackee container:

$ make docker-shell

an additional step is needed to install fittrackee_client

$ make docker-build-client

to start FitTrackee with client dev tools:

$ make docker-serve-client

Open http://localhost:3000

Note

Some environment variables need to be updated like UI_URL

to run lint or tests:

$ make docker-lint-client  # run type check and lint on javascript files
$ make docker-test-client  # run unit tests on Client
$ make docker-lint-python  # run type check and lint on python files
$ make docker-test-python  # run unit tests on API

VSCode¶

Added in version 1.0.4.

Development¶

You can use the Dev Container without the debug configuration and vice versa. Dev Container is strongly recommended on Windows because of path handling issues.

Dev Container¶

Using a Dev Container gives you a ready-to-use environment (Python, Poetry, Node, etc.) without installing them on your host.

Prerequisites

Docker Engine
VS Code with Dev Containers extension

How to use

Open the FitTrackee folder in VS Code.
When prompted, choose Reopen in Container (or open the Command Palette and run Dev Containers: Reopen in Container).

Note

For better file-system performance on Windows/macOS, use an anonymous container volume so code and packages are stored inside the VM filesystem.
Use the Command Palette action Dev Containers: Clone Repository in Container Volume to clone into a volume.
If you rebuild the container frequently, prefer a named volume to preserve installed dependencies between rebuilds.
See Improve performance.

Note

Port 5000 (fittrackee-ui) is forwarded automatically, if you change APP_PORT you need to manually forward the new port using Forward a Port command in the Command Palette.

Debug configuration & tasks¶

This repository includes a VS Code launch configuration that:

starts the full Docker Compose dev stack in the background,
waits until services are healthy,
attaches the debugger to the backend so breakpoints work immediately,
tears the stack down when you stop the debugger.

How to start debugging

Open the Command Palette and run Debug: Start Debugging or press F5.

Note

If the debugger fails to attach, use Debug: Select Debug Session to end the session, check container logs, then run Tasks: Run Task and then down: devcontainer-compose before retrying.

Warning

On Linux, host.docker.internal does not resolve automatically from inside containers. If the debugger fails to attach and logs show connection issues to host.docker.internal:5678, ensure .devcontainer\docker-compose-devcontainer.yml includes the host gateway mapping:

services:
  fittrackee:
    extra_hosts:
      - "host.docker.internal:host-gateway"