Installation

Homer is installed in three steps: the home stack on a server, the app on devices, signing in to the home. The installers aren't published openly: everything for the first two steps is on the install link page.

By invite

The install link comes from someone who already runs Homer: the owner issues it in the web version, Access → Install link, see Access and invites. Know nobody with Homer — send a request on homer.varyen.net, and the author issues one. The link opens the “Install Homer” page with:

• Home server — the install command for Linux or Windows, below;
• Homer app for Android — the Download APK button;
• Homer Node — the Download Homer Node button, the Windows installer. See Homer Node.

The server command, where <home address> is the address of the home that issued the link and <token> is its token; on the link page it's already filled in.

Linux (mini PC, nettop, Raspberry Pi 4/5 on a 64-bit system), Docker required:

curl -fsSL https://<home address>/v1/install-invites/<token>/install.sh | sudo bash

Windows with Docker Desktop, in PowerShell as administrator:

irm https://<home address>/v1/install-invites/<token>/install.ps1 | iex

The installer:

1. checks Docker and Compose (2.24 or newer is required);
2. finds the server address on the home network, the time zone and the Zigbee stick;
3. downloads the signed image archive of the current version from homer.varyen.net (about 310 MB), verifies sha256 and loads the images into Docker; lays out the home folder (/opt/homer, on Windows %USERPROFILE%\homer): compose, .env, Mosquitto configs with a password, Zigbee2MQTT and Home Assistant;
4. brings the home up. The Homer server goes through the Home Assistant first run by itself, takes a token and connects MQTT;
5. prints a QR code. The app scans it in the setup wizard, at the “I have an invite” step, and becomes the owner. Next to it are a code for manual entry and the owner key: write the key down on paper.

Every server install run counts as one install on the link and uses up its limit; downloading the APK doesn't. A closed, expired or used-up link shows an explanation instead of the commands — ask whoever issued it for a new one.

Running it again updates the installation: the shared compose and images are new, data and passwords stay. Settings are variables: HOMER_DIR, HOMER_VERSION, HOMER_IP. If you have access to the private image registry, the same installers work without an invite: curl -fsSL https://homer.varyen.net/install.sh | sudo bash and irm https://homer.varyen.net/install.ps1 | iex.

After that the home updates itself: at 4 am the server checks homer.varyen.net, verifies the release signature and installs the new version of the Homer server, the web version and go2rtc; if it doesn't come up within two minutes, the previous one is restored. The same can be done with a button, see Updating Homer. A home whose server is built from source doesn't update this way.

What isn't on from the start: cameras (docker compose --profile cameras up -d), remote support (--profile support). On Windows the Zigbee stick isn't passed into the container, and HA updates are installed by running the installer again.

The Home Assistant login created by the server is homer, the password is in the server volume: docker exec homer-sidecar cat /data/setup/ha-•••.json.

Below is how the stack is built, if you install or fix it by hand.

What you need

• An install link — from someone who already runs Homer, or from the author by request on homer.varyen.net.
• A home server that stays on: mini PC, nettop, home server. Linux or Windows with WSL2, Docker with Compose.
• A Zigbee USB stick, if the home has Zigbee devices. Put it on an extension cable away from USB 3.0 ports: they jam the radio.
• Devices with Android 7 or newer: phone, tablet, Android TV, Meta Quest headset.
• Optionally, a Windows computer for the Homer speaker.

Home stack

Everything on the server side is one Docker Compose project named homer. The file is deploy/docker-compose.yml in the repository. On the server it sits in the project folder, next to the services' data: Home Assistant config, Zigbee2MQTT and Mosquitto data, Homer server and web version sources.

Service	Container	Port	What it does
mosquitto	mosquitto	1883	MQTT broker for Zigbee2MQTT and Wi-Fi devices
zigbee2mqtt	zigbee2mqtt	8080	Zigbee bridge: stick ↔ MQTT. Its web interface is on 8080
homeassistant	homeassistant	8123	Home Assistant
sidecar	homer-sidecar	8730, 8731	Homer server: home, files, access, log, alarms
app	homer-app	8740, 8741	Homer web version
gate	homer-gate	8124	Splitter for the external entry: one domain for the home, Homer server, web and hub
go2rtc	homer-go2rtc	—	Camera video. Serves it only through the Homer server
updater	homer-updater	—	Updates Home Assistant on request from the Homer server, see Updates
hub	homer-hub	—	Remote support hub, only needed by an integrator. See Support
web	homer-web	8081	Simple web page on top of Home Assistant, without the Homer server

Settings of a specific home — Homer server addresses for devices, the Alice skill, the speaker, speaches, the support hub, the router — are in .env next to compose. The sample is deploy/.env.example; an empty value turns the feature off.

The Homer server and the web version are built from source on the server itself. To bring everything up:

docker compose up -d --build

You can rebuild one service without touching the others: docker compose up -d --build sidecar.

Homer server and Home Assistant

The Homer server needs a Home Assistant long-lived access token — the HA_TOKEN variable in sidecar/.env on the server. You create it in Home Assistant: Profile → Security → Long-lived access tokens → Create token.

Token of the home's account

Use a token of the account the home lives under. A token of another account gives an empty home without a single error in the log.

If you revoke the token in Home Assistant, the Homer server stops seeing the home: the plan isn't read, commands don't go through. Create a new one, replace it in sidecar/.env and recreate the container: docker compose up -d --force-recreate sidecar.

Check

From a device on the home network, open http://<server address>:8730/v1/health. The entry field in the response should be internal. From outside, through the external address, it should be external. If both addresses answer the same, the entries are mixed up, and it's better to find out on installation day.

Two entries

The Homer server and the web version each have two entries: home and external. Based on which entry a request came through, the Homer server decides whether the home can be controlled. Access without the “Remote access” permission controls the home only from inside.

Entry	Homer server	Web version	Who can reach it
Home	8730	8740	The whole home network
External	8731, only on the server's 127.0.0.1	8741	Reverse proxy, router port forwarding

The Homer server's external entry is published only on the server's 127.0.0.1 on purpose. If you publish it to the home network, the “at home / outside” difference stops meaning anything.

External address

From outside, the home opens on one domain. The router or a reverse proxy terminates TLS and passes everything to homer-gate (port 8124), which routes by path:

Path	Where
/v1/	Homer server external entry
/web/	web version
/hub/	support hub
everything else	Home Assistant

An external address isn't required. Without it, the home is reachable only from the home network, and that's fine.

App

One APK build for phone, tablet, TV and headset.

• Phone and tablet — plan in portrait, plan with a room panel in landscape.
• TV — controlled with the remote. The app appears in the Android TV launcher. The automation canvas isn't on TV, but the automation list with “enable” and “run” buttons is.
• Meta Quest — a walk through the home in the headset, see Plan and walk.

The first time, the APK is downloaded from the install link page, the Download APK button: it's the same build the issuing home's server hands out to its own devices. After that the app updates itself from its own home's Homer server: at most once every three hours it asks for the version, downloads the build and installs it. On the first update Android asks for permission to install apps from this source. The update status is shown by the version in the settings header; tapping it checks right away.

Signing in to the home

The first time the app opens, you get the first-run wizard, not an address and token.

1. Owner. On the first device, choose I have an invite in the wizard and scan the QR code the installer printed. Nothing to scan with — type the code from the installer screen by hand and enter the Homer server address (http://<address>:8730). The device becomes the owner. Write down the owner key the installer printed: it signs you in to the web version and gets the home back if the app was removed. If the stack was built by hand, without the installer, the path through Home Assistant admin rights is described in Owner.
2. Other devices sign in by invite: the owner shows a QR code, the device scans it. A TV types the code by hand. To bring in several people at once, use an open link. More — Invite.
3. A browser signs in with an invite link or the owner key on the web version sign-in page.

Then place devices on the plan: Settings → Devices → Devices on the plan.

A local address is more reliable

The app lives on the same network as the home. With the home address, lights switch even without internet.

Next

The first time you open the app or the web version, you get the first-run wizard: a flat template, connection and the first light.