Ion-Homepage

A self-hosted browser home page — clock, calendar, agenda, todos, links,
and live control of Home Assistant, UniFi and Proxmox.

---

Screenshots

Staged examples with fictional data.

Install

curl -fsSL https://forgejo.dom.network/domuk/Ion-Homepage/raw/branch/main/install.sh | sudo bash

Installs anything missing, puts it in your home directory, starts it, and tells you the address to open. It needs elevated privileges during installation; the application itself belongs to you, not to root.

Development checkout

The source checkout workflow is for contributors who already have a working development tree. New installations should use the HTTPS installer above; it downloads the release manifest, verifies the selected version archive, and hands the extracted release to manage.

The application lives in your home directory rather than /opt; on SteamOS, Silverblue and other read-only systems /opt is either not writable or reset by an OS update. /home survives both.

Then

The installer prints every address it can be reached on. Open one and work through the setup — your account, time zone, and whether the network you are on is yours. Existing source checkouts can use ./manage install directly.

Trusting that network means the home page opens without signing in from anywhere on it, and stays signed in. The admin always asks for your password, wherever you are, and from outside that network so does everything else.

Your browser will warn you, once. It says "Your connection is not private". That is expected — the certificate it made for itself encrypts the connection but cannot prove the server is yours, because nothing signed it. Click Advanced and continue; it will not ask again. To stop it happening at all, let the app get a real one: Settings → Certificate asks Let's Encrypt for a certificate for your domain, proves it with a DNS record in Cloudflare (nothing has to be open to the internet), and renews it by itself. Or point HP_TLS_CERT and HP_TLS_KEY at a certificate of your own.

---

Commands

./manage install	Set it up and start it
./manage uninstall	Remove it, data and all
./manage service	Start automatically on boot
./manage unservice	Stop starting on boot
./manage versions	What versions exist, and which is running
./manage update	Move to the newest version
./manage update 1.4.0	Move to a specific version
./manage rollback	Go back to the previous version
./manage password	Set or reset the login
./manage start · stop · restart	Run it
./manage status	Is it running, which version, where
./manage address	Every address it can be reached on
./manage logs	Watch what it is doing

---

Ion-Save

Share anything from an Android phone — a video, a recipe, a link, a note — and it waits in the Ion-Save box on the home page until it has been read.

1. Admin → Integrations → + Add integration → Ion-Save → Save.
2. On the Ion-Save page, Configure → QR code address: pick the address your phone reaches this server on. The machine's own addresses are listed; choose Custom for a public IP or domain.
3. Scan Get the app with the phone's camera and install it.
4. Press Pair a phone, name it, and scan the code from the app — or, on the same phone, tap Enter code in the app and paste the pairing text.
5. Manage, under Ion-Save in the admin menu, lists everything saved, with bulk archive, restore and delete.

The app's source is in android/; see android/README.md to build it.

---

Home Assistant cards

Three kinds of card built from Home Assistant, each a module on the home page:

• Weather - Ecowitt — outdoor temperature, feels-like, humidity and dew point; a wind compass with speed and gust; rain with week and month; a pressure gauge; UV; indoor temperature and humidity.
• Energy — what the house is using now on a live dial with a running graph and its cost per hour; electricity and gas today with cost, week, month, unit rate and standing charge; and smart sockets with their watts and an on/off. Money is in the meter's currency, or one you set.
• Heating — thermostats, A/C units and hot water, added one at a time with + Add device. Each shows only the controls Home Assistant says it has: on/off, modes, target temperature or range, presets, fan speed, swing, humidity; for hot water, its modes and away.

Admin → Home Assistant → Cards → + Weather - Ecowitt, + Energy - Glow or + Heating. Weather and Energy find their readings by the names Home Assistant's Ecowitt integration and a Glow smart meter give them; for another station or meter, Edit and pick each reading. Scan first if a device was added to Home Assistant since.

Every card — these and the service cards — has Export and Import in its editor: the card's setup as text, to keep or to copy onto another card.

The Home Assistant box has a tab per room, from Home Assistant's areas. An item's edit box in the admin can put it in another room.

Home Assistant is now live: tiles and cards update as Home Assistant reports a change rather than once a minute.

The weather station card can carry the 5-day forecast instead of the clock (Edit → Show the 5-day forecast on this card). Sockets can be renamed for the card alone, in Edit or with the pencil beside each on the home page.

Layouts

The quickest way: the Edit button in the clock box (signing in first if needed). Drag modules by their handle, or use the arrows, then Save. It edits whatever is open — the home page, or the saved view at that address — and the version for the screen you are on: phone (one column), tablet (two) or desktop (three). Save as new view… turns the arrangement into a saved view of its own.

Admin → Appearance & layout → Default layouts arranges the home page for each kind of screen: Phone (one column), Tablet (two columns — open foldables and narrower windows) and Desktop (three columns, 1400 pixels and over). The tablet layout balances itself until you arrange it: modules go, in the phone order, into whichever column is shorter. Reset to automatic goes back to that. Saved layouts are separate pages at their own address, and have the same three versions — phone, tablet and desktop. On a wide screen, a column left empty is left out.

---

Hawser (Docker)

Docker hosts running Hawser in standard mode — the agent Dockhand talks to — can be watched and controlled here too. One integration per host:

1. Admin → Integrations → + Add integration → Hawser (Docker).
2. Base URL is the host and Hawser's port, http://192.168.1.50:2376 (https:// if Hawser was given a certificate); Hawser token is the TOKEN it was started with. Hawser in edge mode dials out to Dockhand and cannot be reached from here.
3. Scan, then approve containers (and the host) onto Infrastructure. Approving asks what each should be called on the home page, and warns when a name is already taken by something else there.

Running containers show CPU and memory; one stopped on purpose is Off, one that crashed is Down, and one restarting over and over or reporting unhealthy needs attention. Click a container for its details and Start, Stop or Restart.

---

More integrations

Each is added under Admin → Integrations → + Add integration, scanned, and approved onto Infrastructure like the rest. Clicking one on the home page opens its details: gauges, readings, lists and, for some, buttons.

Integration	Address	Credentials	Shows
UPS (NUT)	192.168.1.50:3493 (upsd)	Only if upsd asks	On mains / on battery / low, charge, load, runtime
Uptime Kuma	http://host:3001	API key (Settings → API Keys)	Every monitor: up, down, pending, response time, certificate days
Ping / port check	—	—	Your list of targets: NAS = 192.168.1.10, Printer = 192.168.1.20:631, Blog = https://example.com
Pi-hole	http://host	Password or app password	Queries, blocked share, blocklist size; Pause 5 min / Resume
AdGuard Home	http://host:3000	Username and password	Queries, blocked share, busiest clients; Pause 5 min / Resume
Plex	http://host:32400	X-Plex-Token	Now playing with progress and transcoding, library counts, recently added posters
Sonarr / Radarr	http://host:8989 / :7878	API key	Downloading, coming up this week, health problems, disk space
qBittorrent	http://host:8080	Web UI username and password	Speeds, active torrents, stalled ones; Pause all / Resume all
Immich	http://host:2283	API key (an admin's for library counts and jobs)	Disk, photos and videos, jobs, the latest photos
TrueNAS	https://host	API key	The system and its alerts, each pool's health, space and scrub, apps
Unraid	http://host	API key (Settings → Management Access)	Array state and space, each disk's status and temperature, shares and their space, Docker, VMs

Pictures (Plex posters, Immich photos) are fetched through Homepage, so keys never reach the browser. When one of these services cannot be reached, what it reported turns unknown rather than staying as it was last seen.

Service cards

Any of these can also be a card on the home page. Open the integration in the admin, then Cards → Make card. Choose what the card shows from everything that integration reports — its numbers, gauges, lists and pictures — rename any of them, set how many entries a list or the pictures show, show a list as posters, and put them in order. Whether the card shows its status, status line, icon and a link to open the app is up to you too. Cards refresh every 10 seconds while the page is open; Plex is checked every 10 seconds, so now playing keeps up. An Unraid card lists whichever of its drives you tick. A card can carry buttons (qBittorrent's pause all and alternative speeds), and its link can open an address of your choosing.

Clicking a card opens more info: a popup with tabs of everything worth seeing about that integration — Plex's streams and history, Sonarr's and Radarr's queue, coming up and missing, every qBittorrent torrent with start, stop and delete, Immich's newest photos, AdGuard's and Pi-hole's query log, and for the rest their drives, containers, guests, devices or monitors. Infrastructure boxes reach the same popup through More info.

Infrastructure tabs

Infrastructure sorts what is approved into tabs by what it is: Hardware (the machines), VMs/Containers, Services, Components, Network, Clients, Security, Voice Assistants and Acked. Anything that needs attention is listed above the tabs, whichever is open. Any item can be hidden from the home page in its edit box and still be used on cards.

Hardware monitoring

Unraid's drives are approved onto Hardware monitoring rather than Infrastructure. They are listed under Infrastructure's Components tab, named with their server ("NAS1 - Disk 2"), with their temperature and space, next to each share's space, two to a row and grouped by type. They reach the problems list only while in alarm.

Network map

The admin's Network map draws every site as a tree from its router down: what is plugged into what, and what runs on each host. Nothing places itself: everything not on the map is listed with a suggestion — from what its integration says, a matching IP or a similar name — to accept, turn down or choose for yourself. + Device adds devices no integration reports, like a datacentre router or a Raspberry Pi, with up to 1024 IPs or ranges; they live on the map only. Lines carry UniFi's switch ports and speeds where it gives them (from its older API, with the same key), or ones you type in. A machine whose IP UniFi sees on a switch port — a server, or a device added by hand — is suggested there, port and speed included. Click a site's header to rename it, set its VPN or remove it. Undo… lists the last 50 map changes and goes back to any of them. Infrastructure popups on the home page show what each item runs on and what runs on it.

House map

The admin's House map draws each floor of the house to real sizes. Add a room by typing its size, click round its corners (typing a wall's length as you go), or trace over a picture of the plan once its scale is set with two clicks. Read rooms from it reads the picture by itself — plain image logic in the browser, nothing sent anywhere: the walls, every space however small, doors by their swing, windows by their glass, bays, a garage door and the stairs — and then one room's real size typed in scales the whole floor. Every wall read is a wall of its own, to type a length or thickness, split, lengthen to meet the walls ahead, drag or delete; Wall draws more. A floor drawn as rooms works its walls out from them until Make the walls editable. Checks on each floor list a gap in the outside wall, a room with no way in, or a door opening onto a wall. Doors and windows sit on the walls; furniture comes from a catalog with real sizes. Devices — servers, access points and cameras from integrations, and Home Assistant devices — are dragged from Not placed to where they are, and a room named like a device's area offers to take it. The home page shows the same floors with each device in its live status colour; tapping one opens its popup. Undo… goes back through the last 50 changes.

Acknowledging problems

Something down, offline or unknown can be acknowledged with Ack (signing in first, so who and when is recorded). It leaves the problems list until it next reports healthy; then the acknowledgement is dropped, and its next outage is a problem again. Infrastructure's Acked tab lists what is acknowledged and still not fixed, with who and when.

---

V.E.S.P.A. timers

Timers from the V.E.S.P.A. voice assistant show live under the weather in the clock box, counting down, with the ringing ones on top.

1. Admin → Integrations → + Add integration → V.E.S.P.A.
2. Base URL is the V.E.S.P.A. server's address; Username and Password are the ones you sign in to it with. They are stored encrypted and never sent to the browser.
3. Save and test. The status reads Live once its event stream is open.

On the home page, Dismiss stops a ringing timer, ✕ cancels one, and + Timer starts one on a satellite.

When a timer rings, every open home page sounds the alarm and shows a popup with a big Stop timer. Upload your own alarm under Configure → Alarm sound (MP3, OGG or WAV, up to 2 MB); without one a built-in tone plays. Browsers stay silent on a page nobody has touched since it loaded, so tap an always-on screen once after opening it.

To watch the satellites in the Infrastructure box, open Import under V.E.S.P.A., Scan, and approve them. Each shows Up or Down as the live connection reports it.

---

Settings

HP_PORT	Port to serve on. Default 443.
HP_DATA_DIR	Where the database lives. Default ./data.
HP_TLS_CERT HP_TLS_KEY	Use your own certificate.
HP_PROXY_ADDRESSES	Reverse proxies whose forwarded client address is trusted.

HP_PORT=8443 ./manage install

---

Updating

Admin → Settings → Version, or ./manage update.

The updater reads updates/manifest.json and downloads updates/versions/<version>.zip over HTTPS. It checks the archive size and SHA-256 before extraction; runtime updates do not require Git. The new version is built beside the running one and switched to in a single step. Update coordination uses flock when available and an atomic process marker otherwise, so the updater does not require the flock utility.

This replaces the Git-based updater. Existing installations whose old updater cannot reach the repository cannot receive this change through that failed update path. Fresh installations use the new manifest updater.

---

Backups

Admin → Settings → Back up now creates a consistent database backup in data/backups/. Integration credentials in data/secret.key, certificates in data/cert.pem and data/key.pem, and the update source in data/update-source.json are retained separately by the installation. If HP_SECRET_KEY_FILE, HP_TLS_CERT, or HP_TLS_KEY points outside data/, those external files are separate from the in-app backup as well.

./manage uninstall does not — it removes everything, database included, and says so before it asks you to confirm. Copy the file first if you want it.

Forgotten the password:

./manage password