Getting started advanced

Default Credentials

Username: admin
Password: admin

Docker Deployment

Endurain provides a Docker image for simplified deployment. To get started, check out the docker-compose.yml.example file in the project repository and adjust it according to your setup. Supported tags are:

latest: contains the latest released version;
version, example "v0.3.0": contains the app state available at the time of the version specified;
development version, example "dev_06092024": contains a development version of the app at the date specified. This is not a stable released and may contain issues and bugs. Please do not open issues if using a version like this unless asked by me.

Supported Environment Variables

Table below shows supported environment variables. Variables marked with optional "No" should be set to avoid errors.

Environment variable	Default value	Optional	Notes
UID	1000	Yes	User ID for mounted volumes. Default is 1000
GID	1000	Yes	Group ID for mounted volumes. Default is 1000
TZ	UTC	Yes	Timezone definition. Useful for TZ calculation for activities that do not have coordinates associated, like indoor swim or weight training. If not specified UTC will be used. List of available time zones here. Format `Europe/Lisbon` expected
FRONTEND_DIR	`/app/frontend/dist`	Yes	You will only need to change this value if installing using bare metal method
BACKEND_DIR	`/app/backend`	Yes	You will only need to change this value if installing using bare metal method
DATA_DIR	`/app/backend/data`	Yes	You will only need to change this value if installing using bare metal method
LOGS_DIR	`/app/backend/logs`	Yes	You will only need to change this value if installing using bare metal method
ENDURAIN_HOST	No default set	`No`	Required for internal communication and Strava. For Strava https must be used. Host or local ip (example: http://192.168.1.10:8080 or https://endurain.com)
REVERSE_GEO_PROVIDER	nominatim	Yes	Defines reverse geo provider. Expects geocode, photon or nominatim. photon can be the SaaS by komoot or a self hosted version like a self hosted version. Like photon, Nominatim can be the SaaS or a self hosted version
PHOTON_API_HOST	photon.komoot.io	Yes	API host for photon. By default it uses the SaaS by komoot
PHOTON_API_USE_HTTPS	true	Yes	Protocol used by photon. By default uses HTTPS to be inline with what SaaS by komoot expects
NOMINATIM_API_HOST	nominatim.openstreetmap.org	Yes	API host for Nominatim. By default it uses the SaaS
NOMINATIM_API_USE_HTTPS	true	Yes	Protocol used by Nominatim. By default uses HTTPS to be inline with what SaaS expects
GEOCODES_MAPS_API	changeme	Yes	Geocode maps offers a free plan consisting of 1 Request/Second. Registration necessary.
REVERSE_GEO_RATE_LIMIT	1	Yes	Change this if you have a paid Geocode maps tier. Other providers also use this variable. Keep it as is if you use photon or Nominatim to keep 1 request per second
DB_HOST	postgres	Yes	postgres
DB_PORT	5432	Yes	3306 or 5432
DB_USER	endurain	Yes	N/A
DB_PASSWORD	No default set	`No`	Database password. Alternatively, use `DB_PASSWORD_FILE` for Docker secrets
DB_DATABASE	endurain	Yes	N/A
DB_SSLMODE	(empty)	Yes	Optional TLS mode for the PostgreSQL connection. Leave empty to disable (default — keeps local Postgres without SSL working). Accepted values match libpq: `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`. Recommended for any deployed environment: `require`. Most secure (validates CA + hostname): `verify-full`
SECRET_KEY	No default set	`No`	Run `openssl rand -hex 32` on a terminal to get a secret. Alternatively, use `SECRET_KEY_FILE` for Docker secrets
FERNET_KEY	No default set	`No`	Run `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"` on a terminal to get a secret or go to https://fernetkeygen.com. Example output is `7NfMMRSCWcoNDSjqBX8WoYH9nTFk1VdQOdZY13po53Y=`. Alternatively, use `FERNET_KEY_FILE` for Docker secrets
ALGORITHM	HS256	Yes	Currently only HS256 is supported
ACCESS_TOKEN_EXPIRE_MINUTES	15	Yes	Time in minutes
REFRESH_TOKEN_EXPIRE_DAYS	7	Yes	Time in days
SESSION_IDLE_TIMEOUT_ENABLED	false	Yes	Enforce idle timeouts (supported values are `true` and `false`)
SESSION_IDLE_TIMEOUT_HOURS	1	Yes	Time in hours
SESSION_ABSOLUTE_TIMEOUT_HOURS	24	Yes	Time in hours
JAEGER_ENABLED	false	Yes	N/A
JAEGER_PROTOCOL	http	Yes	N/A
JAEGER_HOST	jaeger	Yes	N/A
JAEGER_PORT	4317	Yes	N/A
BEHIND_PROXY	false	Yes	Change to true if behind reverse proxy
ENVIRONMENT	production	Yes	`production`, `demo` and `development` allowed. `development` allows connections from localhost:8080 and localhost:5173 at the CORS level. `demo` equals to `production` except it does not return user sessions
SMTP_HOST	No default set	Yes	The SMTP host of your email provider. Example `smtp.protonmail.ch`
SMTP_PORT	587	Yes	The SMTP port of your email provider. Default is 587
SMTP_USERNAME	No default set	Yes	The username of your SMTP email provider, probably your email address
SMTP_PASSWORD	No default set	Yes	The password of your SMTP email provider. Some providers allow the use of your account password, others require the creation of an app password. Please refer to your provider documentation. Alternatively, use `SMTP_PASSWORD_FILE` for Docker secrets
SMTP_SECURE	true	Yes	By default it uses secure communications. Accepted values are `true` and `false`
SMTP_SECURE_TYPE	starttls	Yes	If SMTP_SECURE is set you can set the communication type. Accepted values are `starttls` and `ssl`
LOG_LEVEL	info	Yes	Supported levels: critical, error, warning, info, debug, trace
FRONTEND_PROTOCOL	http	Yes	Protocol used for cookie security. Set to `https` when running behind HTTPS to enable the `Secure` flag on authentication cookies
ALLOWED_REDIRECT_SCHEMES	(empty)	Yes	Comma-separated list of custom URI schemes allowed as SSO redirect targets for mobile apps using the system browser (e.g., `gadgetbridge,myapp`). Defaults to empty — only relative paths (e.g., `/dashboard`) are accepted. External `http`/`https` URLs are always rejected regardless of this setting. See Mobile SSO with PKCE
TRUSTED_PROXIES	"*"	Yes	Comma-separated list of trusted proxy IPs or CIDR ranges for correct client IP detection when `BEHIND_PROXY` is `true`. Defaults to `["*"]` (all proxies trusted) in development and `[]` in production and demo
RATE_LIMIT_ENABLED	true	Yes	Enable or disable API rate limiting. Set to `false` to disable for development or testing. Accepted values are `true` and `false`
RATE_LIMIT_STORAGE_URI	memory://	Yes	Storage backend URI for rate limit counters. Use `memory://` for single-worker deployments or `redis://redis:6379/0` for multi-worker setups so all workers share counters.
AUTH_SECURITY_STORAGE_URI	No default set	Yes	Storage backend URI for auth security state, including login lockout, pending MFA login state, and temporary MFA setup secrets. Defaults to `RATE_LIMIT_STORAGE_URI` when unset. Use `memory://` for single-worker deployments or Redis for shared multi-worker protection.

Table below shows the obligatory environment variables for postgres container. You should set them based on what was also set for the Endurain container.

Environemnt variable	Default value	Optional	Notes
POSTGRES_PASSWORD	changeme	`No`	N/A
POSTGRES_DB	endurain	`No`	N/A
POSTGRES_USER	endurain	`No`	N/A
PGDATA	/var/lib/postgresql/data/pgdata	`No`	N/A

To check Python backend dependencies used, use poetry file (pyproject.toml).

Frontend dependencies:

To check npm dependencies used, use npm file (package.json)
Logo created on Canva

Session Timeout Configuration (Optional)

By default, Endurain sessions last 7 days without enforcing idle timeouts. For enhanced security, you can enable automatic session expiration:

Environment Variables:

SESSION_IDLE_TIMEOUT_ENABLED: Enable timeout enforcement (default: false)
SESSION_IDLE_TIMEOUT_HOURS: Logout after inactivity (default: 1)
SESSION_ABSOLUTE_TIMEOUT_HOURS: Force re-login after duration (default: 24)

Example:

environment:
  SESSION_IDLE_TIMEOUT_ENABLED: "true"
  SESSION_IDLE_TIMEOUT_HOURS: "2"
  SESSION_ABSOLUTE_TIMEOUT_HOURS: "48"

Docker Secrets Support

Endurain supports Docker secrets for securely managing sensitive environment variables. For the following environment variables, you can use _FILE variants that read the secret from a file instead of storing it directly in environment variables:

DB_PASSWORD → DB_PASSWORD_FILE
SECRET_KEY → SECRET_KEY_FILE
FERNET_KEY → FERNET_KEY_FILE
SMTP_PASSWORD → SMTP_PASSWORD_FILE

Using File-Based Secrets

Use file-based secrets to securely manage sensitive environment variables:

Create a secrets directory with proper permissions:

mkdir -p secrets
chmod 700 secrets

Create secret files with strong passwords:

# Use randomly generated passwords, not hardcoded ones
echo "$(openssl rand -base64 32)" > secrets/db_password.txt
echo "$(openssl rand -hex 32)" > secrets/secret_key.txt
echo "$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")" > secrets/fernet_key.txt

# Set secure file permissions
chmod 600 secrets/*.txt
chown $(id -u):$(id -g) secrets/*.txt

Configure docker-compose.yml:

services:
  endurain:
    environment:
      - DB_PASSWORD_FILE=/run/secrets/db_password
      - SECRET_KEY_FILE=/run/secrets/secret_key
      - FERNET_KEY_FILE=/run/secrets/fernet_key
    secrets:
      - db_password
      - secret_key
      - fernet_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  secret_key:
    file: ./secrets/secret_key.txt
  fernet_key:
    file: ./secrets/fernet_key.txt

Note: When using _FILE variants, the original environment variables (e.g., DB_PASSWORD) are not needed. The application will automatically read from the file specified by the _FILE environment variable.

Volumes

Docker image uses a non-root user, so ensure target folders are not owned by root. Non-root user should use UID and GID 1000. It is recommended to configure the following volumes for data persistence:

Volume	Notes
`<local_path>/endurain/backend/logs:/app/backend/logs`	Log files for the backend
`<local_path>/endurain/backend/data:/app/backend/data`	Necessary for image and activity files persistence on docker image update

Image personalization

It is possible (v0.10.0 or higher) to personalize the login image in the login page. To do that, map the data/server_images directory for image persistence on container updates and: - Set the image in the server settings zone of the settings page - A square image is expected. Default one uses 1000px vs 1000px