Skip to content

Latest commit

 

History

History
112 lines (74 loc) · 4.78 KB

README.md

File metadata and controls

112 lines (74 loc) · 4.78 KB
Raw

Home Assistant Add-on: NGINX Home Assistant SSL proxy

Sets up an SSL proxy with NGINX and redirects traffic from port 80 to 443.

Supports aarch64 Architecture Supports amd64 Architecture Supports armhf Architecture Supports armv7 Architecture Supports i386 Architecture

About

Sets up an SSL proxy with NGINX web server. It is typically used to forward SSL internet traffic while allowing unencrypted local traffic to/from a Home Assistant instance.

Make sure you have generated a certificate before you start this add-on. The Duck DNS add-on can generate a Let's Encrypt certificate that can be used by this add-on.

Installation

Follow these steps to get the add-on installed on your system:

  1. Navigate in your Home Assistant frontend to Supervisor -> Add-on Store.
  2. Find the "NGINX Home Assistant SSL proxy" add-on and click it.
  3. Click on the "INSTALL" button.

How to use

The NGINX Proxy add-on is commonly used in conjunction with the Duck DNS add-on to set up secure remote access to your Home Assistant instance. The following instructions covers this scenario.

  1. The certificate to your registered domain should already be created via the Duck DNS add-on or another method. Make sure that the certificate files exist in the /ssl directory.
  2. In the configuration.yaml file, some options in the http: section are no longer necessary for this scenario, and should be commented out or removed:
    • ssl_certificate
    • ssl_key
    • server_port
  3. Change the domain option to the domain name you registered (from DuckDNS or any other domain you control).
  4. Leave all other options as-is.
  5. Save configuration.
  6. Start the add-on.
  7. Have some patience and wait a couple of minutes.
  8. Check the add-on log output to see the result.

Configuration

Add-on configuration:

domain: home.example.com
certfile: fullchain.pem
keyfile: privkey.pem
hsts: "max-age=31536000; includeSubDomains"
customize:
  active: false
  default: "nginx_proxy_default*.conf"
  servers: "nginx_proxy/*.conf"
cloudflare: false

Option: domain (required)

The domain name to use for the proxy.

Option: certfile (required)

The certificate file to use in the /ssl directory. Keep filename as-is if you used default settings to create the certificate with the Duck DNS add-on.

Option: keyfile (required)

Private key file to use in the /ssl directory.

Option: hsts (required)

Value for the Strict-Transport-Security HTTP header to send. If empty, the header is not sent.

Option customize.active (required)

If true, additional NGINX configuration files for the default server and additional servers are read from files in the /share directory specified by the default and servers variables.

Option customize.default (required)

The filename of the NGINX configuration for the default server, found in the /share directory.

Option customize.servers (required)

The filename(s) of the NGINX configuration for the additional servers, found in the /share directory.

Option cloudflare (optional)

If enabled, configure Nginx with a list of IP addresses directly from Cloudflare that will be used for set_real_ip_from directive Nginx config. This is so the ip_ban_enabled feature can be used and work correctly in /config/customize.yaml.

Known issues and limitations

  • By default, port 80 is disabled in the add-on configuration in case the port is needed for other components or add-ons like emulated_hue.

Support

Got questions?

You have several options to get them answered:

In case you've found a bug, please open an issue on our GitHub.