DOCSEARCHbyAlgolia
Submit Docs

Beaver Habit Tracker

repository·main·Indexed 23 days ago

https://github.com/daya0576/beaverhabits

A self-hosted habit tracking application designed without a 'Goals' abstraction. It features high extensibility with support for Home Assistant switches, CalDAV bridges, and native iOS clients. The system is built with FastAPI and supports multiple storage types (SQLite database or local JSON files), Google One Tap authentication, and real-time updates via WebSockets for habit ticks and list metadata.

Tokens
6.3K
Snippets
9
Records
41
Agent score
83%

What's inside beaverhabits

  1. Configure Beaver Habit Tracker environment variables

    main

    To use the Beaver Habit Tracker API, you must configure the following environment variables:

    • BEAVERHABITS_API_KEY (Required): Your permanent API token. You can generate this by logging into your Beaver Habits instance, navigating to Menu → Tools → API Tokens, and clicking Generate API Token.
    • SERVER_URL (Optional): The URL of your Beaver Habits server. Defaults to https://beaverhabits.com (useful for self-hosted instances).

  2. Deploy Beaver Habit Tracker with Docker

    main

    You can run Beaver Habit Tracker as a containerized service. The container is designed to start as a non-privileged user for security and OpenShift compatibility. To avoid permission issues, ensure the UID owning your host volume matches the UID used in the container.

    docker run -d --name beaverhabits \
  -u $(id -u):$(id -g) \
  -e HABITS_STORAGE=USER_DISK \
  -v ./beaver/:/app/.user/ \
  -p 8080:8080 \
  daya0576/beaverhabits:latest

  3. Deploy Beaver Habit Tracker with Docker Compose

    main

    Use Docker Compose for a more configurable deployment. Key configuration options include HABITS_STORAGE (choose USER_DISK for local JSON files or DATABASE for a single SQLite habits.db) and TRUSTED_LOCAL_EMAIL to skip authentication. Ensure the user field matches your host user permissions to prevent volume access issues.

    services:
  beaverhabits:
    container_name: beaverhabits
    user: 1000:1000 # User permissions of your docker or default user.
    environment:
      # See the link below to find all the environment variables
      # https://github.com/daya0576/beaverhabits/wiki/Environment-variables
      - HABITS_STORAGE=USER_DISK # DATABASE stores in a single SQLite database named habits.db. USER_DISK option saves in a local json file.
      - TRUSTED_LOCAL_EMAIL=your@email.com # Skip authentication
      - INDEX_HABIT_DATE_COLUMNS=5 # Customize the date columns for the index page.
      - ENABLE_IOS_STANDALONE=true
    volumes:
      - ./beaver/:/app/.user/ # Change directory to match your docker file scheme.
    ports:
      - 8080:8080
    restart: unless-stopped
    image: daya0576/beaverhabits:latest

  4. Set up a local development environment

    main

    BeaverHabits uses uv for package management. To set up the development environment, create a virtual environment, sync dependencies, and run the development server using the provided script.

    # Install uv and all the dependencies
uv venv && uv sync

# Start the server
./start.sh dev

  5. Understand the application startup lifecycle

    main

    BeaverHabits uses a FastAPI lifespan manager to handle initialization tasks before the server starts accepting requests. The following sequence occurs during startup:

    1. Configuration Validation: Checks if ADMIN_EMAIL is present when REQUIRE_ADMIN_FOR_REGISTRATION is enabled.
    2. Debug Mode Setup: If settings.DEBUG is enabled, it sets the asyncio loop to debug mode and reduces slow_callback_duration to 0.01.
    3. Database Initialization: Calls create_db_and_tables() to ensure the database and necessary tables exist.
    4. Scheduler Startup: If settings.ENABLE_DAILY_BACKUP is enabled, it schedules the daily_backup_task() in the event loop.
    5. Route Registration: Initializes metrics, auth, API, Astro, Paddle (if ENABLE_PLAN is true), and GUI routes.
    6. Sentry Integration: If settings.SENTRY_DSN is provided, Sentry is initialized.

  6. Run BeaverHabits in debug mode

    main

    The main.py entrypoint is designed to be run via a production server. It can be executed directly for development purposes only if DEBUG is enabled in the settings. When run directly, it starts a Uvicorn server on 0.0.0.0:9001 with a single worker.

    Note: Running this script directly in production is prohibited and will raise a RuntimeError if DEBUG is not set.

  7. Configure Google One Tap authentication

    main

    To use Google One Tap, you must provide a GOOGLE_ONE_TAP_CLIENT_ID obtained from the Google Cloud Console.

    Setup Requirements:

    • For local development, add http://localhost:8080 to the authorized JavaScript origins.
    • In production, add your website's domain to the authorized JavaScript origins.
    • Ensure <origin>/google/auth is included in the "Authorized redirect URIs".

  8. List habits and view weekly ASCII overview

    main

    To retrieve a list of all habits and their completion status, follow these steps:

    1. Get all habits: Call the /api/v1/habits endpoint to retrieve the list of habits and their IDs.
    2. Get completions: For each habit, call the /api/v1/habits/{habit_id}/completions endpoint to get completion dates. Use the following query parameters:
      • date_fmt: %25d-%25m-%25Y (for DD-MM-YYYY format)
      • date_start: The start date
      • date_end: The end date
      • limit: 100
      • sort: asc

    Response Format: The completions endpoint returns an array of date strings, e.g., ["16-02-2026", "18-02-2026"].

    Visualizing Results: It is recommended to render the results as an ASCII table where ✓ represents a completed habit and ✗ represents an incomplete one. Strip emojis from habit names to ensure proper table alignment.

    # Step 1: Get all habits
curl -s -H "Authorization: Bearer $BEAVERHABITS_API_KEY" \
  "${SERVER_URL:-https://beaverhabits.com}/api/v1/habits"

# Step 2: Get completions for a specific habit ID
curl -s -H "Authorization: Bearer $BEAVERHABITS_API_KEY" \
  "${SERVER_URL:-https://beaverhabits.com}/api/v1/habits/{habit_id}/completions?date_fmt=%25d-%25m-%25Y&date_start={start}&date_end={end}&limit=100&sort=asc"

  9. Mark a habit as complete or incomplete

    main

    Use the complete_habit functionality to update the status of a habit for a specific date.

    Parameters:

    • habit_id: The unique identifier for the habit (resolve this by matching the habit name from the list_habits output).
    • date (Required): The date in DD-MM-YYYY format.
    • done (Optional): Set to true to mark as complete, or false to uncomplete. Defaults to true.
    • date_fmt: Use %d-%m-%Y in the request body.

    Endpoint: POST ${SERVER_URL}/api/v1/habits/{habit_id}/completions

    curl -s -X POST \
  -H "Authorization: Bearer $BEAVERHABITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "20-02-2026", "done": true, "date_fmt": "%d-%m-%Y"}' \
  "${SERVER_URL:-https://beaverhabits.com}/api/v1/habits/{habit_id}/completions"

  11. Configure required settings for registration

    main

    If you enable administrative registration, you must provide an administrator email address. The application validates this during the startup lifespan.

    Requirement:

    • If settings.REQUIRE_ADMIN_FOR_REGISTRATION is True, then settings.ADMIN_EMAIL must be set.

    Error: If this condition is not met, the application will raise: RuntimeError: ADMIN_EMAIL must be set when REQUIRE_ADMIN_FOR_REGISTRATION is enabled