Repository navigation
How To Guide
This guide walks through how to use HomeGlow day to day, and how to set up each of its features. It describes the app as it is on the main branch of the project.
HomeGlow has two halves:
- The dashboard is what everyone in the house sees on a wall display, tablet or phone: the calendar, the chores, the photos, the weather.
- The Admin Panel is where the grown-ups set everything up. Open it from the menu at the bottom of the screen (see The dock).
Menu paths are written the way the app shows them. For example, Family → Chores → Settings means: open the Family tab, then the Chores section, then its Settings view.
- Before you start
- The dashboard, the dock and tabs
- Family: people, chores, routines, prizes and vacation
- Calendar
- Photos
- Weather
- Displays: devices, screensaver and this display's settings
- Look: themes, colors and dark mode
- Security: the admin PIN and controls on displays
- Home Assistant
- Plugins and custom widgets
- Notifications
- System: language, time zone, connections and backups
- Troubleshooting
Once HomeGlow is installed (see Installing), open it in a browser. A new display starts with a Home tab and nothing on it. Set it up in this order:
- Set an admin PIN. Open the Admin Panel, go to Security, and choose SET ADMIN PIN. It must be 4 to 8 digits. Once a PIN is set, opening the Admin Panel asks for it. Do this first, so that little hands can't change the settings.
- Set the time zone. Go to System → Language & Region. The time zone is for the whole household: it decides when a day starts for chores and when the midnight reset happens.
- Add your family. Go to Family → Users and add each person.
- Turn on the widgets you want. Go to Dashboard → Widgets.
- Pick a look. Go to Look and choose a theme and light or dark mode.
Each browser or wall display is a display. Each display has its own tabs, its own widget layout and its own settings. Settings that belong to the whole household (chores, the family, the time zone, the PIN) are shared by all of them.
The dock sits along the bottom of the screen.
-
The HomeGlow logo on the left opens the menu:
- Refresh reloads the page.
- Settings opens the Admin Panel.
- Lock Layout / Move/Resize switches the widgets between locked and movable. This is only on larger screens, not phones.
- Light Mode, Dark Mode or Auto Mode switches the theme for this display.
- Tab buttons come next, one for each tab. Tap one to switch to it.
- The dock fades away after a while without a touch if you have turned on Hide the dock when idle (see This display). Any touch brings it back. Phones always show it.
Each display has tabs, and each tab shows its own set of widgets. The Home tab is always first and can't be renamed or deleted.
To add a tab:
- Go to Dashboard → Tabs.
- Choose ADD TAB.
- Give it a label, pick an icon, and choose whether to show the label on the dock.
To change the order, use the up and down arrows beside each tab. On a desktop browser you can also drag the rows.
Widgets are turned on for the whole household in Dashboard → Widgets. For each one you can choose:
- Enabled, to turn it on or off.
- Transparent Background.
- Auto-Refresh Interval, how often its data is fetched again.
- Show on Tabs, which tabs it appears on. The Chores and Calendar widgets need at least one tab.
The built-in widgets are:
- Chores: the daily chores for each person, with clams, and the bonus chores.
- Calendar: a month or week view of your calendars.
- Photos: a slideshow or grid from your photo sources.
- Weather: the current weather and a three-day forecast.
Plugins add more widgets. See Plugins and custom widgets.
To move or resize a widget on a tab, unlock the layout from the dock menu (Lock Layout turns into Move/Resize). Drag a widget to move it. To resize it, drag a corner. Lock the layout again from the same menu when you're done, so that nobody moves things by accident.
If you have a second display set up the way you want, you can copy its tabs and widget settings onto another display. Go to Displays → Devices, and use the copy button on the display you want to set up. Be careful: this replaces the tabs and widgets already on the display you copy to.
Go to Family → Users.
- Add a family member with a username and an email address, then choose ADD USER.
- Pick an avatar. Choose CHOOSE for a built-in picture, or UPLOAD to use a photo of the person.
- Order. The order here is the order people appear on the dashboard. Drag a row, or use the arrows on a touch screen.
- Clam Total shows each person's balance. The bonus user is for chores nobody has been given yet; it is always pinned at the top.
Chores have three parts. A chore is what needs doing and how many clams it's worth. A schedule is who it's for and when it comes round. A history entry records each time it was done.
- Go to Family → Chores → Definitions.
- Choose NEW CHORE, and give it a title, an optional description and a clam value. A chore worth 0 clams still counts toward the day.
- Under Schedules, choose New Schedule and pick who the chore is for.
Each chore can have more than one schedule, for example a different person on different days.
- Who it's for: a family member, or Unassigned (Bonus) (see Bonus chores).
-
When it repeats:
- Preset, for common patterns such as daily.
- Days of Week, to choose the days.
- Custom Crontab, for a pattern that the other two can't describe.
- One-time task (no recurrence), for something that happens once.
-
Duration: how long it stays on the list.
- Day Of shows it only on its scheduled day.
- Until Completed keeps it on the list until it's done. It stays there even if it's not done on the day.
- Once Completed keeps it on the list, then shows it again after an interval you choose, such as every three minutes.
- Due date (optional): a deadline. The chore turns yellow when it is due and red when it is overdue.
- Due time (optional): the time of day. It's required for a sound.
- Play sound when due: rings a chime on the displays at the due time, and can repeat every so many minutes until the chore is done.
- Expires: turns the chore red after a set time, so that a child has to ask a parent to finish it. See Chores that expire.
- Transferable: lets someone hand the chore to another person from the dashboard.
- Can snooze/defer: lets someone hide the chore until a later time.
On the dashboard, each chore has a button on the right. Tap it to finish the chore: the card shows that it's done and the clams are added to the person's total. Tap the undo arrow to take it back.
A chore with an icon shows the icon in place of the checkmark until it's done.
Press and hold a chore for about half a second, or right-click it on a computer, to open its menu:
- Transfer chore gives it to someone else.
- Snooze due date hides it until a time you choose.
- History shows the chore's record.
If a chore has an expiry time, it turns red when that time passes, and its chime stops ringing. Tapping an expired chore asks the child to get a parent. A parent can answer Yes, which asks for the admin PIN, and the chore is completed with its full clams. The history records it as Approved late. A chore can only be finished late by a parent, even from another screen.
A bonus chore has no one assigned. It appears in the Bonus Chores panel under the daily chores, and anyone can take it from there. A person can only have one uncompleted bonus chore at a time, and unclaimed bonus chores reset each night.
A chore can start another chore when it's done. Open the chore's edit dialog and choose When it's done to add up to three follow-ups: "Then give Unload the dishwasher to Liam, after 2 hours." A follow-up can be given at once, or after a delay of up to seven days. Follow-ups start when the first chore is completed that day, by anyone. Work completed for an earlier day doesn't hand anything on. Unticking the first chore takes back any follow-ups nobody has done yet.
When someone finishes all of their daily chores, they earn a bonus. Set the amount in Family → Chores → Settings → Daily Completion Clam Reward. The same page has the Celebrate switch, which shows confetti on every display.
Under Family → Chores → Settings, turn on Enable chore due-time sounds, and choose the default sound and volume. Each schedule can then play its own sound when due, and you can upload your own sounds. Each display can also be muted with the bell button on the Chores widget.
Family → Chores → History lists what has been done and missed. Filter by range, person or chore, group the results, and tick Show missed to include chores that weren't done. Adjustments and bonuses are listed separately.
Tap a family member's picture on the dashboard to open Redeem clams. Use it to record clams spent outside the prize store, such as a toy bought on a trip. Add a note if you like. The spending is recorded in the history, and the balance goes down.
A routine is a checklist of steps a child ticks off, such as Brush teeth, Make bed, Get dressed. Each routine counts as one chore for the day.
Step 1: make the steps. Go to Family → Routines → Steps, choose NEW STEP, and give it a name and an icon. A step can be used in any routine.
Step 2: make the routine. Go to Family → Routines → Routines, choose NEW ROUTINE, and then:
- Choose who it's for. A routine can be for several people at once; each gets their own copy and their own ticks.
- Choose when it runs: on certain weekdays, or on days when a calendar event matches a word you choose, such as "soccer". A routine on calendar events can be set to be due a number of minutes before the event.
- Choose the steps, in the order they should be done.
- Optionally, set an end time, and a reward: for example, 5 clams for every 7 days in a row. Steps never pay out; only the streak does.
On the dashboard, a routine appears on the Chores widget with its steps. Tick each one as it's done. Ticking the last step completes the routine. Unticking a step takes it back. The card shows the streak, and whether the routine was finished on time.
Prizes are things the family can spend clams on.
- Go to Family → Prizes.
- Choose Add New Prize, give it a name and a clam cost. Tick Repeatable if the prize can be won again and again, such as movie night.
- To put a prize in the Prize Store, use the ➕ next to it. Each store offer can be taken once, unless the prize is repeatable.
On the dashboard, a child opens the Prize Store (🛍️ on the Chores widget) and requests a prize. A parent approves or declines the request there, and the clams are taken off the balance on approval. A prize can be shared: choose Split cost and tick who is taking part. Each person pays an equal share.
Vacation mode is for when the whole family is away.
- Go to Family → Vacation.
- Tick Enable Vacation Mode. You can give it a start and an end date; it turns itself off after the end date.
- Tick Mute chore sounds while on vacation if you don't want chimes.
- Choose SAVE VACATION MODE SETTINGS.
While vacation mode is on, every display shows a vacation animation as its screensaver, and missed chores aren't counted against anyone. Switching it on asks for the admin PIN, because it pauses chore tracking for the whole house.
The Calendar widget shows events from one or more calendars, in a month or week view.
- Open the Calendar widget's settings (the ⚙️ at the top right of the widget).
- Choose Add Calendar under Calendar Sources.
- Choose a Calendar Type and fill in its details:
- ICS (Public Calendar Link): paste the link. This is read-only.
- CalDAV (Private Server): the calendar's address, a username and a password.
- Apple iCloud Calendar: your Apple ID and an app-specific password, made in your Apple account settings. This is read-only.
- Google Calendar: connect your Google account first (see Google Calendar Syncing). Events then sync both ways, so you can add, edit and delete events in HomeGlow.
- Choose a colour for the calendar and save. Use Sync now to fetch its events straight away.
- Switch views with the month and week buttons in the widget's header.
- Move between periods with the arrows. Tap the month name to jump back to today.
- Add an event with Add event. For a Google calendar, you can also pick an event colour.
- Edit or delete an event from its event editor.
The settings gear gives you:
- Merge duplicate events across calendars: when the same event is on two calendars, show it once.
- Start calendar with current week, and how many weeks to show.
- Days to show and Days per row, for the month view.
- Show start times, and the text and bullet sizes for events.
- Auto-return to today: after this many minutes without a touch, the calendar jumps back to today. The default is 20 minutes; 0 turns it off.
The Photos widget shows a slideshow or a grid from one or more photo sources.
Open the widget's settings (⚙️) and choose Add Source. There are three kinds:
- Immich: a photo library on your own server. Enter the Immich server's address and an API key (from Immich's Settings → API Keys). Leave Album ID empty to show every photo, or enter an album's ID to show just that album.
- HomeGlow Photos: photos uploaded to HomeGlow itself. Save the source first, then choose Open upload page. The upload page works on a phone, so you can add pictures straight from your camera roll.
- Google Photos: connect your Google account first, then choose Pick photos in Google Photos. The photos you pick are downloaded to your server, so they keep working even when Google is unreachable.
Use Test Connection to check an Immich source. The slideshow speed is set in the same settings.
The Weather widget shows the current conditions and a three-day forecast. It takes its information from one of two sources.
- Get a free API key from openweathermap.org/api.
- Go to System → Connections, paste the key under OpenWeatherMap API Key, and choose SAVE API KEYS.
- Set the location in the Weather widget's settings, along with the units.
If you run Home Assistant, you can use its weather instead of an API key. See Home Assistant. Choose Home Assistant as the Weather Source under System → Connections. Some Home Assistant weather entities don't report everything (air quality or feels-like temperature, for example); the widget hides what's missing rather than showing blanks.
Each browser or wall display is a device, and it has its own name.
Go to Displays → Devices.
- Current Device Name shows the name of the display you're using. Use the pencil icon to rename it.
- The table lists every display, with when it was last changed and how many widgets it has.
- Copy tabs and widget settings from one display to another, replacing the other display's setup (see Copying a display).
Go to Displays → Screensaver to protect a screen from burn-in.
-
Enable Screensaver, then choose its mode:
- Cycle Through Tabs switches between your tabs, one every few seconds.
- Photo Slideshow shows photos from a photo source. It needs a source set up in the Photos widget.
- Inactivity Timeout sets how long the screen must be untouched before the screensaver starts.
- Keep screen awake: turn this off on a wall display, so that the display's own power settings can dim and sleep the screen.
Go to Displays → This Display. These settings apply to this display only; every display and every phone has its own.
- Hide the dock when idle: the dock fades after this many minutes without a touch. Set 0 to keep it visible.
- Swipe with two fingers to change tabs: swipe left for the next tab and right for the previous one.
- Block pinch zoom: stops a pinch or double-tap from zooming the whole board by accident.
- Let widgets expand: a widget can grow to fill the top half of the screen, or the whole screen, to show more. Tap the dimmed screen around it, or press Escape, to put it back. To expand a widget, double-tap it, or use the expand button that appears in its corner for a few seconds after a touch. Under Choose widgets, you can leave out any widget whose own taps get in the way.
Phones don't use the touch and expand settings, since each widget already fills the screen there.
Go to Look. It has two columns:
- This display changes only this screen.
- Household is the default for every display that doesn't have its own setting.
Each setting can be Use household, or set for this display.
- Theme: the look of the dashboard. Classic comes with HomeGlow. Choose Get themes to browse the themes repository, REFRESH to check for new ones, or ADD A THEME FOLDER to install one you've made yourself.
- Light / Dark / Auto: Auto switches between light and dark at sunrise and sunset for your location.
- Colors: the background, secondary and accent colours.
- Personalize: a background (the theme's own colour, a gradient or a photo), and how see-through the cards are.
Choose SAVE FOR THIS DISPLAY, or MAKE THIS DISPLAY THE HOUSEHOLD DEFAULT to set the look for everyone who has no setting of their own.
Go to Security.
- SET ADMIN PIN asks for 4 to 8 digits. Once a PIN is set, opening the Admin Panel asks for it.
- A display that has entered the PIN can remember it, so that the family doesn't have to type it every time. Require PIN on all devices again makes every display ask for it again.
- Remove PIN turns the protection off. Anyone can then open the Admin Panel.
If the PIN is forgotten, the app has no on-screen reset. Ask for help on the Discord or in a GitHub issue.
Some parent controls are useful on a shared wall display, but not on a kid's tablet. Under Controls on Displays, you choose which controls each display shows:
- Default for new displays: choose Full control or Wall display. New displays, and displays with no setting of their own, follow this.
- Each display: give a specific display its own setting, or leave it on Using household default.
The controls you can hide are: adding a chore, transferring a chore, snoozing a chore, approving prize requests, spending clams from a profile, the calendar's settings, adding or editing calendar events, the photo settings, and the weather settings. Plugins can add their own.
Hidden controls are not locked. They are only hidden on that display. A display that remembers the admin PIN shows everything, so use Require PIN on all devices again if the controls don't seem to apply.
HomeGlow can connect to Home Assistant to use its weather, and to show panels of your devices.
- In Home Assistant, create a long-lived access token. You'll find it at the bottom of your profile page, on the Security tab.
- In HomeGlow, go to System → Connections and fill in the Home Assistant section:
- Home Assistant URL: the address you use to reach Home Assistant, including the port.
- Long-Lived Access Token: the token you just made. It's kept on the server and is never sent to a display.
-
Weather Entity: usually
weather.home. Choose TEST CONNECTION to pick from a list.
- Choose SAVE HOME ASSISTANT.
Go to Dashboard → Home Assistant, and build panels of tiles for your devices, without writing any code:
- Choose devices, or start a panel from an area in one step.
- For each tile, set its label, icon and size, and whether it is view-only or needs a press and hold.
- A tile can show only when another device is in a particular state, such as a light only when someone is home.
- The preview shows the panel as it will look on the dashboard.
Each panel becomes a widget that you can place on any tab. For safety, locks, alarms and garage doors always need a press and hold, and unlocking, disarming or opening them asks for the PIN, unless the display already remembers it.
Plugins are extra widgets, made by other people or by you.
Go to Dashboard → Plugins.
- GitHub Plugin Repository lists the plugins in the HomeGlowPlugins repository, by category. Choose Install, or Update when a newer version is there. REFRESH AVAILABLE PLUGINS checks again.
- Upload Custom Widget lets you add an HTML widget from a file on your computer.
- Plugin Settings lists what's installed. Turn a plugin on or off, set its transparency and refresh interval, choose its tabs, and change any options the plugin offers.
If you build your own, see Custom Widget Development and Plugin Development.
HomeGlow can tell phones when a chore or routine is done, or when someone has finished all of the day's chores, even when HomeGlow is closed. Plugins can send their own messages too. Everything is set up in Admin Panel → System → Notifications, on one page with three ways to deliver the same messages. Use whichever suits your household: browser notifications are enough for most, and ntfy and the Home Assistant app are there for more.
At the top of the page is Address a tap opens: the address of your HomeGlow (for example http://homeglow.lan:3000). Tapping an ntfy or Home Assistant notification opens this address. It starts as the address you're using now; choose Save to keep it.
Each device, ntfy topic and phone chooses for itself:
- Hears about: A chore or routine is done, Someone finishes all of today's chores, and any plugin that can send messages, under Messages from:.
- About: everyone, or only the family members you tick.
Messages come in English or Spanish, in the language the recipient was set up in.
This is the default. A phone or computer gets notifications through its own browser.
- Open HomeGlow on the device you want to set up, go to this page, and choose TURN ON NOTIFICATIONS in the Notifications on this device card. Allow notifications when the browser asks.
- Choose what this device hears about, and about whom.
- Choose Send a test to check it.
The Devices with notifications on table lists every device that has them on, with what it hears, its last message, and buttons to send a test or turn its notifications off.
Things to know:
-
HTTPS is required. Browsers only allow notifications on a secure page. A HomeGlow opened at
http://192.168.…can't send them, so use ntfy or the Home Assistant app there instead. - On an iPhone or iPad, add HomeGlow to the Home Screen first (Share → Add to Home Screen), and open it from there. This needs iOS 16.4 or later.
- A device's notifications are turned off from its own card, or from the table. Deleting a display turns its notifications off too.
ntfy is a free app for Android (including the F-Droid build) and iPhone. It needs no HTTPS and no web app on the Home Screen, so it's a good choice for a phone that browser notifications don't suit.
- Turn on the switch Send notifications with ntfy.
- Set the ntfy server. It's
https://ntfy.shby default, or the address of your own ntfy server. - If your server needs a login, enter an Access token. It's stored encrypted and never shown again. Use Remove token to clear it.
- Choose SAVE NTFY, then TEST CONNECTION to check the server can be reached.
Then add a topic for each phone. A topic is a name the phone subscribes to:
- Choose Add topic and give it a name, such as "Mom's phone".
- Keep the Topic name random. The refresh button makes a new one. Anyone who knows a topic's name can read its messages, so on the public ntfy.sh server a random name matters.
- Choose what the phone hears about, and about whom, then save.
On the phone, open the ntfy app, tap +, and enter the topic name. If you use your own server, choose Use another server and enter its address first.
Each topic's Last message shows whether its last message arrived. Use the bell to send it a test, the pencil to edit it, or the trash can to delete it.
If you have connected Home Assistant (see Home Assistant), every phone with the Home Assistant Companion app appears in this box.
- Turn a phone on with its switch, then choose what it hears about and about whom. Use the pencil to change its name or choices later.
- Look again asks Home Assistant for the list of phones again.
- A phone marked Not in Home Assistant is one you've turned on that Home Assistant no longer lists.
If Home Assistant isn't connected, this box says so and tells you where to connect it.
Plugins can mark a message as urgent, for things that can't wait. An urgent message rings through silent mode where the phone allows it:
- Android (Home Assistant app): the alarm sound.
- iPhone (Home Assistant app): a critical alert. Allow Critical Alerts for the Home Assistant app in the iPhone's settings first.
- ntfy: the highest priority.
- Browser notifications: high urgency.
Chore messages are never urgent. Use urgent sparingly, for things like "the grill is on fire".
- Language is per display. Another device keeps its own language.
- Time Zone is for the whole household. It decides when each day starts for chores and the midnight reset. Calendar times follow each display's own time zone.
Go to System → Connections:
- Weather: the weather source and its API key (see Weather).
- Home Assistant: the connection (see Home Assistant).
- Google Account: connect a Google account for Google Calendar and Google Photos. See Google Calendar Syncing.
- Backup & restore: see below.
Back up everything HomeGlow holds (the database, the encryption key, and the uploaded photos, sounds and themes) to one file.
-
Download a backup saves a
.tar.gzfile. Keep it somewhere safe: it holds the key to every stored password and token. If a PIN is set, HomeGlow asks for it first. - Choose a backup file restores one. HomeGlow checks the file first, saves your current data so you can roll back, and changes nothing until you choose Restart now. Restarting applies the restore. Use Roll back to undo it before restarting.
- Google Drive backups are made every night once a Google account is connected, and the newest 14 are kept. They can be restored from the same place.
When you move HomeGlow to a new server, set ENCRYPTION_KEY on the new server to the key from the backup first (it's in the .encryption-key file inside the archive). Otherwise the stored passwords and tokens can't be read, and the restore is refused.
About shows the version of the display and the server, and the commit each one was built from.
The dashboard is blank. Nothing is placed on the tab yet. Go to Dashboard → Widgets, turn a widget on, and check Show on Tabs.
The calendar says it failed to load. Open the calendar's settings and check its address. For an ICS link, paste it into a browser: it should download a text file.
The weather is blank or says the credentials were rejected. Check the API key or the Home Assistant token under System → Connections, and the location in the Weather widget.
A chore won't finish. It may be expired, which needs a parent. Tap it, and answer Yes with the admin PIN.
A display ignores its controls, or shows more than it should. The display may be remembering the admin PIN. Use Require PIN on all devices again in Security.
Changes don't show on another display. Reload that display. Household settings reach other displays within a few minutes, but a reload is quicker.
Notifications don't arrive. For browser notifications, check that HomeGlow is opened over HTTPS, that the device allows notifications, and (on an iPhone) that it's opened from the Home Screen. For ntfy, check the topic's Last message and the server's address. For the Home Assistant app, check that Home Assistant is connected, and that the phone is still listed.
Something else. Check the container logs (docker compose logs -f), or ask on the Discord or in a GitHub issue.