Developer guide


Setup a dev environment

Bellow are the steps to create a dev environment. Examples bellow will use Endurain repo, but you should adapt those for your scenario (forked repo, etc).

  • Clone the repo to your dev machine:
$ cd <folder_to_store_code>
$ git clone https://github.com/joaovitoriasilva/endurain.git # this will clone the repo structure to the previous folder inside a folder called endurain

Docker image and backend logic

Make sure Docker is installed, more info here.

  • On the project root folder, create a new Docker image, the example bellow uses unified-image as the image name:
$ docker build -f docker/Dockerfile -t unified-image .
  • Go to the project root folder and create a file called docker-compose.yml and adapt it to your needs. Example bellow:
services:
    endurain:
        container_name: endurain
        image: unified-image # based on image that will be created above
        environment:
            - TZ=Europe/Lisbon # change if needed. Default is UTC
            - DB_TYPE=postgres
            - DB_HOST=postgres
            - DB_PORT=5432
            - DB_PASSWORD=changeme
            - SECRET_KEY=changeme # openssl rand -hex 32
            - FERNET_KEY=changeme # https://fernetkeygen.com or python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
            - GEOCODES_MAPS_API=changeme
            - ENDURAIN_HOST=http://localhost:8080 # change if needed
            - BEHIND_PROXY=false
            - ENVIRONMENT=development
        volumes:
            - <path_to_project_root_folder>/backend/app:/app/backend # this will replace the backend code logic with yours. Any changes in the code need a container reboot for them to apply
        ports:
            - "8080:8080" # change if needed
        depends_on:
            postgres:
                condition: service_healthy
        restart: unless-stopped

    postgres:
        image: postgres:latest
        container_name: postgres
        environment:
            - POSTGRES_PASSWORD=changeme
            - POSTGRES_DB=endurain
            - POSTGRES_USER=endurain
            - PGDATA=/var/lib/postgresql/data/pgdata
        ports:
            - "5432:5432"
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U endurain"]
            interval: 5s
            timeout: 5s
            retries: 5
        volumes:
            - <path_to_container_folders>/postgres:/var/lib/postgresql/data
        restart: unless-stopped

    adminer:
        container_name: adminer
        image: adminer
        ports:
            - 8081:8080
        restart: unless-stopped
  • Start your project based on the docker compose file created before:
$ docker compose up -d
  • To stop the project:
$ docker compose down
  • To remove the create unified-image Docker image:
$ docker image remove unified-image
  • Backend uses Poetry for dependency management. You may need to install Python and Poetry if dependency management is necessary.

Frontend

Make sure you have an up-to-date version of Node.js installed.

  • Go to the root of the project and move to frontend/app folder and install the dependencies:
$ cd frontend/app
$ npm install
  • Create a file called .env.local inside frontend/app and add the following to it:
VITE_ENDURAIN_HOST=http://localhost:8080 # Adapt this based on the docker compose of your dev environment
  • After the dependencies are installed run the frontend:
$ npm run dev
  • After the frontend starts running, it should be available in the port 5173. You should now be able to access the dev environment at http://localhost:5173. Screenshot bellow shows the output from the npm run dev. Adapt the port based on the command output.

Frontend running

  • Some processes, like token refresh may redirect your dev env from port 5173 to 8080 (or other, depending on your compose file). If this happens simply navigate again to 5173.

API Integration (v0.3.0+)

Endurain supports integration with other apps:

API Requirements

  • Add a header: Every request must include an X-Client-Type header with either web or mobile as the value. Requests with other values will receive a 403 error.
  • Authorization: Every request must include an Authorization Bearer: <access token> header with a valid (new or refreshed) access token.

Token Handling

  • The backend will generate an access_token valid for 15 minutes and an refresh_token valid for 7 days. This follow the logic of short and longed lived tokens for auth session.
  • The access_token is used for authorization; The refresh_token is used to refresh the access_token.
  • For web apps, the backend sends access/refresh tokens as HTTP-only cookies.
  • For mobile apps, tokens are included in the response body.

API Endpoints

The API is reachable under /api/v1. Below are some example endpoints. All endpoints information can be checked on the backend docs (http://localhost:98/docs or http://ip_address:98/docs or https://domain/docs):

What Url Expected Information
Authorize /token FORM with the fields username and password. This will be sent in clear text, use of HTTPS is highly recommended
Refresh Token /refresh header Authorization Bearer: <Refresh Token>
Activity Upload /activities/create/upload .gpx, .tcx, .gz or .fit file
Set Weight /health/weight JSON {'weight': , 'created_at': yyyy-MM-dd}

Supported activity types

The table bellow details the activity types supported by Endurain.

Name Value
Run 1
Trail run 2
Track run 34
Virtual run 3
Road cycling 4
Gravel cycling 5
MTB cycling 6
Commuting cycling 27
Mixed surface cycling 29
Virtual cycling 7
Indoor cycling 28
Indoor swimming 8
Open water swimming 9
General workout 10
Walk 11
Indoor walk 31
Hike 12
Rowing 13
Yoga 14
Alpine ski 15
Nordic Ski 16
Snowboard 17
Transition 18
Strength Training 19
Crossfit 20
Tennis 21
Table Tennis 22
Badminton 23
Squash 24
Racquetball 25
Pickleball 26
Windsurf 30
Stand up paddling 32
Surf 33

Supported gear types

The table bellow details the gear types supported by Endurain.

Name Value Notes
bike 1 N/A
shoes 2 N/A
wetsuit 3 N/A
racquet 4 N/A
ski 5 N/A
snowboard 6 N/A
windsurf 7 N/A
water_sports_board 8 Example: stand up paddle and surf board

Supported bike component gear types

The table bellow details the bike gear component types supported by Endurain:

Value
back_break_oil
back_break_pads
back_break_rotor
back_tire
back_tube
back_tubeless_sealant
back_tubeless_rim_tape
back_wheel
back_wheel_valve
bottom_bracket
bottle_cage
cassette
chain
computer_mount
crank_left_power_meter
crank_right_power_meter
crankset
crankset_power_meter
fork
frame
front_break_oil
front_break_pads
front_break_rotor
front_derailleur
front_shifter
front_tire
front_tube
front_tubeless_sealant
front_tubeless_rim_tape
front_wheel
front_wheel_valve
grips
handlebar
handlebar_tape
headset
pedals
pedals_left_power_meter
pedals_power_meter
pedals_right_power_meter
rear_derailleur
rear_shifter
saddle
seatpost
stem

Supported shoes component gear types

The table bellow details the shoes component gear types supported by Endurain:

Value
cleats
insoles
laces

Supported racquet component gear types

The table bellow details the racquet component gear types supported by Endurain:

Value
basegrip
bumpers
grommets
overgrip
strings

Supported windsurf component gear types

The table bellow details the windsurf component gear types supported by Endurain:

Value
sail
board
mast
boom
mast_extension
mast_base
mast_universal_joint
fin
footstraps
harness_lines
rigging_lines
footpad
impact_vest
lifeguard_vest
helmet
wing
front_foil
stabilizer
fuselage