What is habitsync?

HabitSync is a self-hosted habit tracking application that lets users create and track habits with flexible scheduling including daily, weekly, monthly, and custom intervals. It supports negative habits to track unwanted behaviors and weekday-specific tracking. The platform includes social features such as shared habits with friends and family, monthly community challenges with voting and leaderboards, and an achievement system with medals. Authentication is handled through OIDC/SSO with support for multiple issuers (tested with Authelia and Google), optional user approval, and basic auth as a fallback. Notifications are sent via Apprise integration supporting 80+ services including Discord, Email, Signal, and Home Assistant. The app provides a Progressive Web App (PWA) for browser installation and a native Android app available from GitHub releases. It runs as a Docker container (image on ghcr.io) with H2 database by default and optional PostgreSQL support. The API is documented via Swagger UI. The project is licensed under BSD-3-Clause.

Should you self-host habitsync?

habitsync scores 47/100 on selfhost.directory (how scoring works) and ranks #22 of 38 in Personal Productivity. It has 346 GitHub stars.

It shipped 4 stable releases in the past year. The latest, v0.19.3, came out on 20 August 2026. New versions land roughly every 5 weeks.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is BSD-3-Clause-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is LanguageTool (75/100, 15 208 stars). It scores higher overall, so compare the two before you pick. See habitsync vs LanguageTool side by side.

Features

Achievement system
Android appIn development, needs to be kept up to date with server version
Apprise notifications
Custom notification schedules
Dark/light mode
Habit Tracking
Monthly challenges
Negative habits
OIDC/SSO Authentication
Optional user approval
Progress comparison
Progressive Web App
Shared habits
Smart notification triggers
Weekday selection

How to install habitsync

Install habitsync with Docker

Environment variables

BASE_URL, APP_SECURITY_BASIC-AUTH-USERS_<username>

docker run
-p 6842:6842
-e BASE_URL=http://localhost:6842
-e 'APP_SECURITY_BASIC-AUTH-USERS_test=$2y$10$EyuJ.fL/PzCTMMKTONEquuFLxAR8SAzl9iXF2v.qDZYCh5K2m78fS'
ghcr.io/jofoerster/habitsync:latest

Quickstart for testing with basic auth

Install habitsync with Docker Compose

Environment variables

BASE_URL, APP_SECURITY_ISSUERS_*, APP_SECURITY_BASIC-AUTH-USERS_*, SPRING_MAIL_*, JWT_SECRET, APPRISE_API_URL, TRACKER_DATEFORMAT_TEMPLATE, PAGE_CHALLENGES_VISIBLE, TRACKER_FIRSTDAYOFWEEK, PUID, PGID, SPRING_DATASOURCE_*

services: web: image: ghcr.io/jofoerster/habitsync:latest environment: - BASE_URL=https://your-domain.com # Choose one or more of the following authentication methods: # OIDC Issuers (tested with Authelia, Google), use public client settings (PKCE flow), # set BASE_URL/auth-callback as redirect, for mobile: habitsync://auth-callback (until 0.18.x: habitsync:///auth-callback) # more than one issuer can be configured # scopes: openid, profile, email # issues setting this up? -> create an issue on github - APP_SECURITY_ISSUERS_<YOUR-ISSUER_NAME>URL= # no trailing / - APP_SECURITY_ISSUERS<YOUR-ISSUER_NAME>CLIENT-ID= - APP_SECURITY_ISSUERS<YOUR-ISSUER_NAME>NEEDS-CONFIRMATION=true # New users need to to be 'let in' by other user, default: true # Google: Use normal web client settings, set CLIENT-SECRET as workaround for Google - APP_SECURITY_ISSUERS_GOOGLE_URL=https://accounts.google.com - APP_SECURITY_ISSUERS_GOOGLE_CLIENT-ID= - APP_SECURITY_ISSUERS_GOOGLE_CLIENT-SECRET= # ONLY AS WORKAROUND FOR GOOGLE, PUBLICALLY AVAILABLE TO CLIENTS! # Login using username and password (basic auth, lower case only!) # Create hash using: htpasswd -bnBC 10 "" password123 | tr -d ':\n' | sed 's/$/$$/g' # $ get replaced with $$ to work in env variables. This might be different in other environments - APP_SECURITY_BASIC-AUTH-USERS= # Mail setup for notifications - SPRING_MAIL_ENABLED=false - SPRING_MAIL_HOST= - SPRING_MAIL_USERNAME= - SPRING_MAIL_PASSWORD= - SPRING_MAIL_PORT=587 # optional SHA-512 hash of your secret key, generate with openssl rand -base64 64. Needed to keep sessions across restarts - JWT_SECRET= - APPRISE_API_URL= # optional, see Notifications section below - TRACKER_DATEFORMAT_TEMPLATE=DD.MM. # optional, only DD, MM supported currently, sets date format in tracker globally - PAGE_CHALLENGES_VISIBLE=true # optional, show challenges page in navigation, set to false to hide globally - TRACKER_FIRSTDAYOFWEEK=MONDAY # optional, overwrites the default first day of week in the activity calendar # available from version 0.17.0: - PUID=1000 # optional, user ID to run as, defaults to 6842 - PGID=1000 # optional, group ID to run as, defaults to 6842 volumes: - :/data #needed for persistent database storage ports: - "6842:6842" # Application accessible under this port - "9092:9092" # For database access, optional

Recommended for production use with full configuration options