Maintainer Note
Thank you for your interest in this project! I originally started it as a personal utility and never expected it to grow so quickly—I’m genuinely thrilled and grateful that it’s become helpful to you and your family.

Please note that I am currently the sole maintainer and manage this repository alongside a full-time job, which means the time I can give to this project is somewhat limited. Responses to issues, pull requests, or questions may be delayed, especially during busy periods at work or at home.

I typically work on the project after office hours or on weekends, depending on my availability and energy. Your patience, understanding, and support mean a lot—thank you for helping make this project better!

🏡 HomeHub: Your All-In-One Family Dashboard

Ever wanted a simple, private spot on your home network for your family's daily stuff? That's HomeHub. It's a lightweight, self-hosted web app that turns any computer (even a Raspberry Pi!) into a central hub for shared notes, shopping lists, chores, a media downloader, and even a family expense tracker.

It’s designed to be easy to use for everyone in the family, with a clean interface that works great on any device.

What Can It Do?

HomeHub is packed with useful tools to make family life a little more organized:

• 📝 Shared Notes: A simple place to jot down quick notes for everyone to see.
• ☁️ Shared Cloud: Easily upload and share files across your home network.
• 🛒 Shopping List: A collaborative list so you never forget the milk again. Comes with suggestions based on your history!
• ✅ Chore Tracker: A simple to-do list for household tasks.
• 🗓️ Calendar & Reminders: A shared calendar to keep track of important dates.
• 👋 Who's Home?: See at a glance who is currently home.
• 💰 Expense Tracker: A powerful tool to track family spending, with support for recurring bills like newspapers, milk, or subscriptions.
• 🎬 Media Downloader: Save videos or music from popular sites directly to your server.
• ...and more, including a Recipe Book, Expiry Tracker, URL Shortener, PDF Compressor, Weather Updates and QR Code Generator!

Salient Features

• Private & Self-Hosted: All your data stays on your network. No cloud, no tracking.
• Simple & Lightweight: Runs smoothly on minimal hardware.
• Family-Focused: Designed to be intuitive for users of all technical skill levels.
• Customizable: Toggle features on or off and even change the color theme right from the config.yml file.

Getting Started is Easy

The best way to run HomeHub is with Docker. It's quick and keeps everything tidy

1. First, copy the config-example.yml to config.yml. This is where you'll name your hub and add family members. You can also set an optional password to protect the whole site.

<details> <summary>Click to see an example config.yml</summary>

instance_name: "My Home Hub"
password: "" #leave blank for password less access
admin_name: "Administrator"
feature_toggles:
  shopping_list: true
  media_downloader: true
  pdf_compressor: true
  qr_generator: true
  notes: true
  shared_cloud: true
  who_is_home: true
  personal_status: true
  chores: true
  recipes: true
  expiry_tracker: true
  url_shortener: true
  expense_tracker: true

family_members:
  - Mom
  - Dad
  - Dipanshu
  - Vivek
  - India

reminders:
  # time_format controls how reminder times are displayed in the UI.
  # Allowed values: "12h" (default) or "24h". Remove or leave blank to fall back to 12h.
  time_format: 12h

  # calendar_start_day controls which day the reminders calendar starts on.
  # Accepts full weekday names (sunday, saturday).  
  calendar_start_day: monday #default is Sunday, comment this line to switch to default

  # Example reminder categories (keys lowercase no spaces recommended)
  categories:
    - key: health
      label: Health
      color: "#dc2626"
    - key: bills
      label: Bills
      color: "#0d9488"
    - key: school
      label: School
      color: "#7c3aed"
    - key: family
      label: Family
      color: "#2563eb"

#Optional settings
theme:
  primary_color: "#1d4ed8"
  secondary_color: "#a0aec0"
  background_color: "#f7fafc"
  card_background_color: "#fff"
  text_color: "#333"
  sidebar_background_color: "#2563eb"
  sidebar_text_color: "#ffffff"
  sidebar_link_color: "rgba(255,255,255,0.95)"
  sidebar_link_border_color: "rgba(255,255,255,0.18)"
  sidebar_active_color: "#3b82f6"

</details>

2. Run with Docker Compose

Use the provided compose.yml file to get started in seconds:

# compose.yml
services:
  homehub:
    container_name: homehub
    image: ghcr.io/surajverma/homehub:latest
    ports:
      - "5000:5000" #app listens internally on port 5000
    environment:
      - FLASK_ENV=production
      - SECRET_KEY=${SECRET_KEY:-} # set via .env; falls back to random if not provided
    volumes:
      - ./uploads:/app/uploads
      - ./media:/app/media
      - ./pdfs:/app/pdfs
      - ./data:/app/data
      - ./config.yml:/app/config.yml:ro

docker compose up -d

That's it! Open your browser and head to http://localhost:5000

Theming

HomeHub follows your system dark/light mode. You can customize colors via config.yml > theme.

Configurable keys:

theme:
  # Accent colors
  primary_color: "#1d4ed8"
  secondary_color: "#a0aec0"
  # Surfaces & text
  background_color: "#f7fafc"
  card_background_color: "#ffffff"
  text_color: "#333333"
  # Sidebar palette
  sidebar_background_color: "#2563eb"
  sidebar_text_color: "#ffffff"                # text color used for the sidebar title and labels
  sidebar_link_color: "rgba(255,255,255,0.95)" # link text color in sidebar items
  sidebar_link_border_color: "rgba(255,255,255,0.18)" # subtle border around sidebar links

Tips:

• Want higher contrast in the sidebar? Increase sidebar_link_border_color opacity (e.g., rgba(255,255,255,0.3)).
• Prefer lighter/darker accents? Tweak primary_color and secondary_color.
• Dark mode palette adapts automatically; the variables above apply to light mode, while dark mode uses tuned counterparts for good contrast.

Weather Widget

HomeHub includes an optional weather widget powered by Open-Meteo, a free weather API. The widget displays current weather conditions and optionally today's forecast on your dashboard.

By default, the weather widget is hidden. You can enable it through config.yml:

weather:
  enabled: true # set to true to show the widget
  label: "" # optional location label (e.g., "Kolkata"). Leave blank to hide.
  latitude: "" # optional, leave empty to use browser geolocation
  longitude: "" # optional, leave empty to use browser geolocation
  timezone: "" # optional, e.g., "Asia/Kolkata" or "America/New_York"; if unset, API uses timezone=auto
  units: metric # metric or imperial (default: metric)
  view: compact # compact or detailed (detailed shows today's forecast: sunrise, sunset, UV, rain %, highs/lows)

Features:

• Two view modes:
  • compact: Shows current temperature, weather condition, feels like, wind (with direction and gusts), humidity, and recent precipitation
  • detailed: Adds today's forecast with sunrise/sunset times, UV index, precipitation probability, and daily high/low temperatures
• Smart caching: Weather data is cached for 15 minutes to respect API rate limits and improve performance
• Flexible location: Use configured coordinates or browser geolocation
• Timezone support: Displays times in your configured timezone, or uses automatic detection
• Unit selection: Choose between metric (°C, km/h, mm) or imperial (°F, mph, mm) units

Privacy Note: When enabled, the widget makes API requests to Open-Meteo's servers. Please review Open-Meteo's privacy policy for details on their data handling practices.

Development Setup

To contribute or run & build HomeHub locally, follow these steps:

1. Clone the Repository

git clone https://github.com/surajverma/homehub.git
cd homehub

2. Python Environment Setup

python -m venv venv
venv\Scripts\activate  # On Windows
pip install -r requirements.txt

3. Configuration

• Copy config-example.yml to config.yml and edit as needed for your family, features, and theme.

4. CSS Build (Tailwind + Custom Styles)

npm install
npm run build:css

• For live CSS rebuilds during development:

npm run watch:css

5. Running the App

• With Docker (recommended):

  docker compose up -d
  

• Locally (for development):

  python run.py
  

  (Ensure you have built CSS and set up your config.)

6. Trou