forked from home-assistant/addons
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Create README for NGINX Proxy (home-assistant#751)
* Create README.md * ✏️ Tweaks and standarization
- Loading branch information
1 parent
8eea01f
commit 4b94c86
Showing
1 changed file
with
109 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# Hass.io Core 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][aarch64-shield] ![Supports amd64 Architecture][amd64-shield] ![Supports armhf Architecture][armhf-shield] ![Supports armv7 Architecture][armv7-shield] ![Supports i386 Architecture][i386-shield] | ||
|
||
## 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](https://github.com/home-assistant/hassio-addons/tree/master/duckdns) add-on can generate a Let's Encrypt certificate that can be used by this add-on. | ||
|
||
## Installation | ||
|
||
The installation of this add-on is straightforward and easy to do. | ||
|
||
1. Navigate in your Home Assistant frontend to **Hass.io** -> **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](https://github.com/home-assistant/hassio-addons/tree/master/duckdns) 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](https://github.com/home-assistant/hassio-addons/tree/master/duckdns) 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: | ||
|
||
```json | ||
{ | ||
"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" | ||
} | ||
} | ||
``` | ||
|
||
### 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](https://github.com/home-assistant/hassio-addons/tree/master/duckdns) add-on. | ||
|
||
### Option: `keyfile` (required) | ||
|
||
Private key file to use in the `/ssl` directory. | ||
|
||
### Option: `hsts` (required) | ||
|
||
Value for the [`Strict-Transport-Security`][hsts] 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. | ||
|
||
## 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: | ||
|
||
- The [Home Assistant Discord Chat Server][discord]. | ||
- The Home Assistant [Community Forum][forum]. | ||
- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] | ||
|
||
In case you've found a bug, please [open an issue on our GitHub][issue]. | ||
|
||
[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg | ||
[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg | ||
[armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg | ||
[armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg | ||
[discord]: https://discord.gg/c5DvZ4e | ||
[forum]: https://community.home-assistant.io | ||
[hsts]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security | ||
[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg | ||
[issue]: https://github.com/home-assistant/hassio-addons/issues | ||
[reddit]: https://reddit.com/r/homeassistant | ||
[repository]: https://github.com/hassio-addons/repository |