OpenWorkouts documentation

About OpenWorkouts

What is it?

The idea behind OpenWorkouts is to provide an open source tool everybody can use to keep track of workouts, in the form of a web-based application.

This includes:

  • Multi-user support, allowing users to signup with an account and then log in and out.
  • Create workouts manually, providing info such as workout day, duration, distance, speed, elevation, etc
  • Create workouts by uploading “tracking files”, like gpx or ANT fit files
  • View workouts on a date-based interface
  • View details of each workout
  • View a profile page for each user with the user workouts, statistics, etc
  • Tools to analize, compare and interact with workouts
  • Tools to share workouts between users, manage club/group workouts and events
  • and many more…

If you are familiar with online services like strava, garmin connect, etc the idea of this project is to provide a similar solution, but in a package you can install locally in your computer or a server of your own.

Who is behind it?

This is an Open Source project, with a community of developers who are working on it for free. You can see a list of people involved in the OpenWorkouts Authors and Contributors page.

Installation instructions

Some things you will need before installing OpenWorkouts

  1. Python: The Python programming language, version 3.x (it has been tested with versions >= 3.5).

  2. Google Chrome + chromedriver: This is not a requirement in order to run OpenWorkouts, but without it, for workouts that have gps tracking data, you won’t get a nice map displaying your route in the workouts lists (you will see the map in the details page though).

    We use Chrome to render a static image out of the route map.

    Note

    chromedriver is usually bundled with Chrome, so installing chrome will install chromedriver too, but in some systems (MacOS for example) you will have to install it separately.

    Note

    (If you prefer you can use Chromium instead of Chrome)

The easiest way, using the installer

This is the easiest way to install OpenWorkouts on any unix-like system (like Linux, any BSD-based system or MacOS).

Grab a copy of the sources, either from https://openworkouts directly or from the github releases page.

Uncompress the tarball or zipped file (depending on what you did download)

Run the installer, in a shell/console:

./bin/install

This script will take all the needed steps to set everything up for you.

Development, how to contribute

What you need

Apart from the dependencies described in the doc:install:, you will need:

  1. git. We use it for the version control of OpenWorkouts.
  2. lessc. We use it for writing modular css code (and generate the definitive css files for OpenWorkouts)

How to access the source code

Main development site

OpenWorkouts development is tracked in our trac site:

https://openworkouts.org/trac

which is publicly available for everybody.

From there you can browse the sources within your web browser, get a copy and access all the development information (tasks, bug reports, milestones, etc).

If you want to get an account and collaborate, get in touch with us at info@openworkouts.org.

Github mirror

We also have a mirror in Github:

https://github.com/openworkouts/OpenWorkouts

Changes made to the OpenWorkouts repositories are populated to Github, so you can grab a copy of the sources from there too (and fork, make pull requests, etc).

What we don’t have replicated in Github is all the development information (tasks, bugs, etc).

Development workflow

We are using the well-known git-flow workflow, with some notes:

  1. The master branch is used to keep track of releases

  2. The current branch is the branch that keeps the main development flow/current.

  3. Each time a developer wants to implement a new feature, first the developer grabs the ticket(s) related to that feature in trac, then a new branch is created from the current branch. Work is done on that branch, which will be merged back to the current branch when it has been finished.

    (more info about this workflow in this tutorial, just remember we use current instead of development for the main development branch)

  4. Features are grouped in milestones, which can be viewed in trac:

    https://openworkouts.org/trac/roadmap

    Once all tasks/tickets in a milestone are done, a release branch is created. OpenWorkouts is then fully tested, no more features can be merged at that time, only bugfixes go into the tree, under that branch.

    When testing has finished, the release branch is then merged into the master branch, that branch is tagged and a release is done

Bug reports are saved into a special milestone:

https://openworkouts.org/trac/milestone/Bug%20reports

When a bug is reported, a developer grabs the ticket containing the bug, checking which version is affected.

If it affects only a specific version, a hotfix branch for that version is created (using tags to create a branch from the specific release tag) and the bugfix is written there.

If it affects all (or several) versions, then the bugfix is developed in a hotfix branch from current, then it is backported to the previous releases.

Again, reading this tutorial will help you get a better picture of this workflow (and in case of any questions, just ping us at info@openworkouts.org)

Documentation

Docs are built using sphinx, written in rst and they are located within the docs/ directory of the main OpenWorkouts repo.

OpenWorkouts Changelog

Release summary

0.2.0, March 1, 2019:
Improvements on user signup, added i18n support for the UI (+ es translations)
0.1.0, February 15, 2019:
Initial release, includes signup/login + per-user complete workout management and an initial set of stats.

Release details

0.2.0

  • New:
    • Added support for different locale/language for the UI (#56, #69) (+ spanish translations)
    • Added user verification by email on signup (#29, #61, #66, #67)
    • Several internal improvements:
      • Added migrations support for the ZODB database (#45)
      • Moved the setup of development environments to use ZEO
      • Added a tasks module to run periodic tasks into separate processes
      • Set logging capabilities and proper log files
  • Fixes:
    • Fixed bug in the profile page yearly stats chart, that caused the wrong weekly/monthly label to be highlighted on page reload.
    • Weeks for the current month were displayed in the wrong part of the yearly activity chart in the profile page (#68)
    • Set a title automatically when adding manually a workout without providing one (#58)
    • Signup form does not keep values on error (#60)
    • Profile images were too big (#51)
    • Fixed several UI problems in mobile devices (#50, #57)
    • Fixed broken bin/install script (+ extended it with some new features)
    • Use a gif “loading” image instead of a fixed image while the screenshot of a workout tracking map is being generated

0.1.0

  • New:
    • User signup and login, password reset and basic user profile management
    • Multi-sport workouts support
      • Add workouts manually or upload using tracking files (gpx and fit supported)
      • Edit/update workouts manually or with tracking files
    • Time-based archive for workouts in the user dashboard
    • Time-based (global, per-month, per-week) stats and charts
    • Detailed view of a workout, including basic workout info, stats and an interactive map for those workouts with gps data

OpenWorkouts Authors and Contributors

OpenWorkouts is an open source project, this file contains an updated list of people contributing to it.

Authors

Indices and tables