Bharat's digital garden

Guide: Setting Up Home Assistant with HomeKit Bridge while using RunTipi & Tailscale

Here is the gist of how all this works together

  • Home assistant needs to run on the local network accessible so that devices can ping and communicate with it
  • Homekit integration will be using multicast DNS over 21063 (mDNS for short) to establish a homekit bridge between the server on the network & iPhone.
  • Since both Tipi & HA run in docker, we’ll need to install mDNS repeater on Tipi and use it to forward mDNS packets from HA.

It might look like a lot, but I promise it’ll be pretty straightforward. Feel free to contact me on twitter if you run into any issues!

Step 1: Configuring Home Assistant

First, we need to make sure Home Assistant is properly configured to work with HomeKit:

  1. Open your Home Assistant configuration file (configuration.yml this is situated at runtipi/app-data/homeassistant-1/data/config/configuration.yaml).
  2. Add the following HomeKit configuration:
homekit:
  name: Bridge
  port: 21063
  advertise_ip: "192.168.0.101"  # Replace with your Home Assistant IP
  1. Save the file and restart Home Assistant.

Step 2: Setting Up mDNS Repeater

To ensure proper communication between HomeKit and Home Assistant, we need to set up mDNS repeater:

  1. Identify your network interfaces by running docker exec <container_id> ifconfig , here the container ID is the ID of the docker container of Home assistant
  2. run route -n to figure out what’s the network name of the IP address you got above
  3. Install mDNS repeater app from runtipi appstore. Start the mDNS repeater with mDNS repeater app with the host interface (e.g., enp1s0) and the Docker network interface (e.g., br-fd25fefeed1f).

Step 3: Configuring RunTipi

Now, let’s configure RunTipi to expose the necessary ports:

  1. Navigate to your RunTipi configuration directory: ~/runtipi/user-config/homeassistant-1/
  2. Edit the docker-compose.yml file:
services:
  homeassistant-1:
    dns:
      - ${DNS_IP}
    ports:
      - 21063:21063
  1. Save the file and restart the Home Assistant app on RunTipi.

Step 4: Setting Up HomeKit Integration

  1. In Home Assistant, go to Configuration > Integrations.
  2. Add a new integration and search for “HomeKit”.
  3. Follow the prompts to set up the HomeKit integration.
  4. Once complete, you’ll see a QR code or a pairing code.

Step 5: Pairing with iOS Device

  1. Open the Home app on your iOS device.
  2. Tap the “+” button to add a new accessory.
  3. Scan the QR code or manually enter the pairing code provided by Home Assistant.
  4. Wait for the connection to be established. This may take a moment.

Troubleshooting

If you encounter issues:

  1. Ensure all ports are correctly forwarded and not blocked by firewalls.
  2. Double-check that the mDNS repeater is running correctly.
  3. Verify that the HomeKit integration in Home Assistant is using the correct port (21063).
  4. If using Tailscale or other VPN solutions, ensure they’re not interfering with local network discovery.

Conclusion

By following these steps, you should now have Home Assistant successfully integrated with HomeKit through RunTipi. This setup allows you to control your smart home devices using Apple’s Home app and Siri, providing a seamless experience across your Apple devices.

Special mention & Massive shout-out to jigsawfr from Runtipi discord for helping me set it up for the first time!