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. The shared calendar can be enabled with feature_toggles.calendar, and the weekly grid can start on the day configured under reminders.calendar_start_day.

Click to see an example config.yml

instance_name: "My Home Hub"
password: "" #leave blank for password less access
admin_name: "Administrator"
max_upload_mb: 1024 # largest upload in MB (Shared Cloud, PDFs); 0 removes the limit
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
  calendar: 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"

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
    volumes:
      - ./uploads:/app/uploads
      - ./media:/app/media
      - ./pdfs:/app/pdfs
      - ./data:/app/data
      - ./config.yml:/app/config.yml:ro
    environment:
      - FLASK_ENV=production
      - SECRET_KEY=${SECRET_KEY:-} # set via .env; falls back to one kept in data/secret_key
      # - TZ=Asia/Kolkata # optional; see "Timezone" below

docker compose up -d

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

Admin password (optional)

By default anyone can pick the admin user from the user switcher. To protect it, the server owner can set an admin password from the host:

docker exec -it homehub flask set-admin-password

• You are asked to type the password twice. Only a salted hash is stored, in data/app.db; nothing is written to config.yml.
• Once set, switching to the admin user asks for the password. Family members keep switching freely.
• Run the same command again to change it. A forgotten password is fixed the same way.
• docker exec -it homehub flask set-admin-password --clear removes it and restores the default behaviour.
• Not using Docker? Run flask set-admin-password from the project folder.

The password in config.yml is separate: it protects the whole site and keeps working as before.

Logins and admin unlocks survive a restart: if SECRET_KEY is not set, HomeHub generates one on first start and keeps it in data/secret_key.

Timezone (optional)

HomeHub decides what "today" is (due dates, overdue chores, recurring expenses and chores) and which time to show next to "By … at …" from the container's clock, which is UTC by default. If you are far from UTC, "today" can roll over a few hours early or late. Set your timezone with TZ in compose.yml:

    environment:
      - TZ=Asia/Kolkata

Use a name from the tz database, then run docker compose up -d. Leaving it out keeps the old UTC behaviour.

Theming

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

Configurable keys (all optional):

theme:
  # Accent colors
  primary_color: "#1d4ed8"
  secondary_color: "#a0aec0"
  # Surfaces & text
  background_color: "#f8fafc"
  card_background_color: "#ffffff"
  text_color: "#0f172a"
  # Sidebar palette. Leave these out for the default light sidebar.
  # Setting sidebar_background_color gives a coloured sidebar with light links.
  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
  sidebar_active_color: "#3b82f6"              # background of the current page's link

Tips:

• The old default blue sidebar (#2563eb) is treated as "not set", so configs copied from an older config-example.yml get the new light sidebar. Pick any other colour to keep a coloured sidebar.
• 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. Troubleshooting

• If you see missing dependency errors, ensure you have run both pip install -r requirements.txt and npm install.
• If port 5000 is in use, stop the conflicting service or change the port in compose.yml and config.yml.
• For Docker issues, try docker compose down then docker compose up -d.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are always welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.

Disclaimer & Security Notice

This software is being provided to the community "as is." This means it comes without any warranty or guarantee of any kind. While I've done my best to build it, I can't promise it will be perfect, fit your exact needs, or be 100% free of bugs.

Please be aware that you are using this software at your own risk. The authors and contributors are not responsible for any problems, damages, or data loss that might occur from using it.

🛡️ Important Security Notice

This project is built for use on a local or trusted network (like your home).

It is not designed or hardened to be safely exposed to the public internet. If you choose to host this software publicly, you are solely responsible for performing a full security review and adding the necessary protections before you do so.

🌤️ Weather Data & Third-Party Services

The optional weather widget uses Open-Meteo, a free weather API service. When the weather widget is enabled:

• Your browser makes requests to Open-Meteo's servers to fetch weather data
• Location coordinates (latitude/longitude) are sent to their API
• Open-Meteo has its own privacy policy and terms of service

By enabling the weather widget, you acknowledge that weather data is provided by a third-party service and is subject to their policies. HomeHub itself does not store or process weather data beyond local browser caching.

Have Fun!

This project was built to be a practical tool for my own family, and I hope it's useful for yours too.

If you find HomeHub useful, you can buy me a coffee ☕.