mirror of
https://github.com/aljazceru/addons.git
synced 2025-12-17 05:04:21 +01:00
Create README for NGINX Proxy (#751)
* Create README.md
* ✏️ Tweaks and standarization
This commit is contained in:
committed by
Franck Nijhof
parent
8eea01f049
commit
4b94c869a2
109
nginx_proxy/README.md
Normal file
109
nginx_proxy/README.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user