Reverse Proxy with Apache

:warning: This guide has been migrated from our website and might be outdated. Feel free to edit this guide to update it, and to remove this message after that.

This example demonstrates how you can configure Apache to act as a proxy for Home Assistant.

This is useful if you want to have:

  • a subdomain redirecting to your Home Assistant instance
  • several subdomains for several instances
  • HTTPS redirection

Subdomain

So you already have a working Apache server available at example.org. Your Home Assistant is correctly working on this webserver and available at http://localhost:8123

Enable mod_proxy_wstunnel by running if you encounter issues while serving Home Assistant through your proxy:

sudo a2enmod proxy_wstunnel

To be able to access to your Home Assistant instance by using https://home.example.org, add the following file to /etc/httpd/conf/extra/ as hass.conf

<VirtualHost *:443>
  ServerName home.example.org
  ProxyPreserveHost On
  ProxyRequests off
  ProxyPass /api/websocket ws://localhost:8123/api/websocket
  ProxyPassReverse /api/websocket ws://localhost:8123/api/websocket
  ProxyPass / http://localhost:8123/
  ProxyPassReverse / http://localhost:8123/

  RewriteEngine on
  RewriteCond %{HTTP:Upgrade} =websocket [NC]
  RewriteRule /(.*)  ws://localhost:8123/$1 [P,L]
  RewriteCond %{HTTP:Upgrade} !=websocket [NC]
  RewriteRule /(.*)  http://localhost:8123/$1 [P,L]
</VirtualHost>

and make sure that this file is read by Apache’s main configuration file /etc/httpd/conf/httpd.conf

...
Include conf/extra/hass.conf
...

If you don’t want HTTPS, you can change <VirtualHost *:443> to <VirtualHost *:80> or better consider redirecting all HTTP to HTTPS.

In case you are getting occasional HTTP 504 error messages ("Gateway Timeout") or HTTP 502 messages ("Bad Gateway") when accessing the Web UI through your proxy, try adding disablereuse=on to both ProxyPass directives:
<VirtualHost *:443>
  [...]
  ProxyPass /api/websocket ws://localhost:8123/api/websocket disablereuse=on
  [...]
  ProxyPass / http://localhost:8123/ disablereuse=on
  [...]
</VirtualHost>

Multiple Instance

You already have Home Assistant running on http://localhost:8123 and available at home.example.org as describe before. The configuration file for this Home Assistant is available in /home/alice/.homeassistant/configuration.yaml

You want another instance available at https://countryside.example.org

You can either :

  • Create a new user, bob, to hold the configuration file in /home/bob/.homeassistant/configuration.yaml and run Home Assistant as this new user
  • Create another configuration directory in /home/alice/.homeassistan2/configuration.yaml and run Home Assistant using hass --config /home/alice/.homeassistant2/

In both solution, change the port number used by modifying configuration.yaml

http:
  server_port: 8124
  ...

Start Home Assistant: Now, you have another instance running on http://localhost:8124

To access this instance by using https://countryside.example.org add to /etc/httpd/conf/extra/hass.conf

<VirtualHost *:443>
  ProxyPreserveHost On
  ProxyRequests Off
  ServerName countryside.example.org
  ProxyPass /api/websocket ws://localhost:8123/api/websocket
  ProxyPassReverse /api/websocket ws://localhost:8123/api/websocket
  ProxyPass / http://localhost:8124/
  ProxyPassReverse / http://localhost:8124/
</VirtualHost>

HTTP to HTTPS redirection

Add to your /etc/httpd/conf/extra/hass.conf

<VirtualHost *:80>
  ServerName example.org
  ServerSignature Off

  RewriteEngine on
  RewriteCond %{HTTPS} !=on
  RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [NE,R,L]
</VirtualHost>
7 Likes

I just used this guide on 20th of August 2020, to setup an Apache Reverse Proxy with SSL and it is spot on. I would have edited the message at the top to note this but cannot find a button to edit it just add a reply.

I use the same settings.

I have an Apache webserver with a real domain name already and SSL certificates (has nothing to do with Home Assistant). This method allows me to use that as a reverse proxy on same IP and same SSL certs and just a subdomain to access my Home Assistant. It works great and the above seems totally up to date

Hi guys. This configuration addresses the following issues:

  • External proxy to internal IP
  • HTTP redirect to HTTPS configuration
  • Wrong IP Address showed in login notifications within Home Assistant
  • Websockets don’t work properly
  • Addons don’t work
<VirtualHost *:80>
        ServerName        homeassistant.adamoutler.com #MODIFY to your host name
        ServerAdmin       [email protected] #MODIFY to your email
        RewriteEngine On
        # This will enable the Rewrite capabilities
        RewriteCond %{HTTPS} !=on
        # This checks to make sure the connection is not already HTTPS
        RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>

<IfModule mod_ssl.c>
<VirtualHost *:443>

		#Declare server
        ServerName        homeassistant.adamoutler.com #MODIFY to your host name
        ServerAdmin       [email protected] #MODIFY to your email

        #fix detecting incorrect login IP by proxy server
        RemoteIPInternalProxy 192.168.1.1  #MODIFY to your proxy, or delete if you aren't using a firewall
        RemoteIPHeader X-Forwarded-For

        #proxy server setup
        ProxyPreserveHost On
        ProxyRequests Off
        ProxyPass /api/websocket ws://192.168.1.8:8123/api/websocket #MODIFY to your HA IP:Port
        ProxyPassReverse /api/websocket wss://192.168.1.8:8123/api/websocket #MODIFY to your HA:Port
        ProxyPass / http://192.168.1.8:8123/ #MODIFY to your HA IP:Port
        ProxyPassReverse / http://192.168.1.8:8123/ #MODIFY to your HA IP:Port

        #fix websockets for addons and apis
        RewriteEngine On
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteRule ^/?(.*) "ws://192.168.1.8:8123/$1" [P,L] #MODIFY to your HA IP address


        #Set security on certan areas(some redacted)
        <Location "/">
                Satisfy any
#               Include /path/to/mySecuritySettings.conf
        </Location>
        <Location "/api">
                Satisfy any
        </Location>

        #HTTPS certs
#        Include /path/to/sites-available/ssl.conf
#        Include /path/to/options-ssl-apache.conf
#        SSLProxyEngine On
#        SSLCertificateFile /path/to/my-chain.pem
#        SSLCertificateKeyFile /path/to/my-cert.pem
</VirtualHost>
</IfModule>

I just switched to Apache2 and I’m trying to get this working. I’m trying to create a proxy to my home assistant but it fails. I have modified adamoutler’s example. I’m trying to access home assistant using https://ha.xxxx.com which should redirect to 192.168.1.1.8123.

<VirtualHost *:443>
	    ServerName ha.xxxx.com
	    SSLEngine on
	    SSLCertificateFile	/etc/letsencrypt/live/xxx/fullchain.pem
		SSLCertificateKeyFile /etc/letsencrypt/live/xxx/privkey.pem
				
        ProxyPreserveHost On
        ProxyRequests Off
        ProxyPass /api/websocket ws://192.168.1.1:8123/api/websocket
        ProxyPassReverse /api/websocket wss://192.168.1.1:8123/api/websocket
        ProxyPass / https://192.168.1.1:8123/
        ProxyPassReverse / https://192.168.1.1:8123/

        #fix websockets for addons and apis
        RewriteEngine On
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteRule ^/?(.*) "ws://192.168.1.1:8123/$1" [P,L] #MODIFY to your HA IP address
	</VirtualHost>

With the current configuration I get 500 internal server error from the apache2 server which should be doing the proxying. Do I need to enable SSL from the home assistant configuration or can it remain http? Any help is truly appriciated :slight_smile:

– edit–
I commented out one of the lines from the apache’s config:

ProxyPreserveHost On
        ProxyRequests Off
        # ProxyPass /api/websocket ws://192.168.1.1:8123/api/websocket
        ProxyPassReverse /api/websocket wss://192.168.1.1:8123/api/websocket
        ProxyPass / http://192.168.1.1:8123/
        ProxyPassReverse / http://192.168.1.1:8123/

        #fix websockets for addons and apis
        RewriteEngine On
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteRule ^/?(.*) "ws://192.168.1.1:8123/$1" [P,L] #MODIFY to your HA IP address

With that I can see HA login page. But when HA is using only http I get the following error:

WebSocket connection to 'wss://ha.xxxx.com/api/websocket' failed: Error during WebSocket handshake: Unexpected response code: 500

And if HA is using SSL I get a proxy error from the apache itself:

/frontend_latest/core.2755f59a.js GET https://ha.xxxx.com/auth/authorize?response_type=code&redirect_uri=https%3A%2F%2Fha.xxxxx.com%2F%3Fauth_callback%3D1&client_id=https%3A%2F%2Fha.xxxx.com%2F&state=ey...502 (Proxy Error)

So something is wrong in the configuration file which I can’t understand.

I run Apache reverse proxy.
In 99.9% of the cases the 192.168.1.1 is the router. Are you sure your IPs are right?

My Home Assistant has no SSL. The reason I use reverse proxy is that I run a website on a machine running Apache with an SSL certificate and real domain pointing to fixed IP address, so I let the Apache take care of the SSL and behind Home Assistant runs on a different machine all clear.

If your router allows hairpin routing so you can access your external domain name from your internal LAN, it makes things easier for your mobile devices.

I’m 110% sure that my HA is running on the 192.168.1.1 address. I can access it with http://192.168.1.1:8123 and it works nicely. But I want to close a port from the internet to the HA and thus I need to use Apache and some kind of proxy configuration. I’ve already created certificates for my public static ip but the HA is not running on that machine. That’s why the proxy.

Can you please share your complete apache2 -config if possible that is working atm?

Okay sorry for the trouble… I really should start reading instructions better. I forgot proxy_wstunnel completely. I thought I had it because websockets work with OctoPrint instances the same way as this one. But apparently not.

Thanks for this, it helped a scrub guy with same name as me solve alot. He says thank you very much! :clown_face:

I’m trying to follow these instructions so I can access HA at home.myhouse.local on my local network over http. I am not trying to access my HA from outside of my local network, and I’m not trying to access/force access via https.

I’m using avahi to publish my server’s “name” on the local network, and I can successfully browse to myhouse.local and see the default Apache page. But when I try to browse to home.myhouse.local, I get a DNS_PROBE_FINISHED_NXDOMAIN error.

What am I missing? Is there something I need to configure in configuration.yaml that I’m not aware of? In my router’s settings?

Thank you!

In order to make some add-ons to work (for example: File Editor or Studio Code Server) on a public subdomain behind apache reverse proxy I need to add this line to the VirtualHost:

http-response set-header X-Frame-Options SAMEORIGIN

I also have these lines in configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.1.50      # Add the IP address of the proxy server
2 Likes

Thanks! This worked for me.

Hello,

Sorry but I’m a bit lost.
I did not follow this tutorial because I already have an apache system for other VMs, and when I apply the same configuration, it does not work:

 I installed HA on a proxmox VM.
 I have an apache server on which I put an SSL LE certificate.
 I configured apache to access from outside with a subdomain.
 My router is configured to redirect all 80 and 443 flow to the apache VM.
 I have indicated in the network parameters the URL of my domain

When I try to go there, I am asked for my login and password, and then I have the error:

Unable to connect to Home Assistant.
Retrying in 6 seconds…

My configuration .:

Can you say me how resolve my issu ?

thanks !

FYI, the use of Apache as a reverse proxy is not recommended by the maintainer of aiohttp due to its use of threading for concurrency. There’s a note in the aiohttp documentation essentially saying it’s unsupported.
However if it works with no problems for you then by all means continue using it. Otherwise, haproxy or nginx are good alternatives.

Ok tanks.
With nginx it’s ok :slight_smile: