letsencrypt: Split documentation (home-assistant#1309)

letsencrypt/DOCS.md

@@ -0,0 +1,203 @@
+# Home Assistant Add-on: Letsencrypt
+
+## 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 "letsencrypt" add-on and click it.
+3. Click on the "INSTALL" button.
+
+## How to use
+
+To use this add-on, you have two options on how to get your certificate:
+
+### 1. http challenge
+
+- Requires Port 80 to be available from the internet and your domain assigned to the externally assigned IP address
+- Doesnt allow wildcard certificates (*.yourdomain.com).
+
+### 2. dns challenge
+
+- Requires you to use one of the supported DNS providers (See "Supported DNS providers" below)
+- Allows to request wildcard certificates (*.yourdomain.com)
+- Doesn’t need you to open a port to your Home Assistant host on your router.
+
+### You always need to provide the following entries within the configuration
+
+```yaml
+email: [email protected]
+domains:
+  # use "*.yourdomain.com" for wildcard certificates.
+  - yourdomain.com
+challenge: http OR dns
+```
+
+IF you choose "dns" as "challenge", you will also need to fill:
+
+```yaml
+# Add the dnsprovider of your choice from the list of "Supported DNS providers" below
+dnsprovider: ""
+```
+
+In addition add the fields according to the credentials required by your dns provider:
+
+
+```yaml
+propagation_seconds: 60
+cloudflare_email: ''
+cloudflare_api_key: ''
+cloudflare_api_token: ''
+cloudxns_api_key: ''
+cloudxns_secret_key: ''
+digitalocean_token: ''
+dnsimple_token: ''
+dnsmadeeasy_api_key: ''
+dnsmadeeasy_secret_key: ''
+google_creds: ''
+gehirn_api_token: ''
+gehirn_api_secret: ''
+linode_key: ''
+linode_version: ''
+luadns_email: ''
+luadns_token: ''
+nsone_api_key: ''
+ovh_endpoint: ''
+ovh_application_key: ''
+ovh_application_secret: ''
+ovh_consumer_key: ''
+rfc2136_server: ''
+rfc2136_port: ''
+rfc2136_name: ''
+rfc2136_secret: ''
+rfc2136_algorithm: ''
+aws_access_key_id: ''
+aws_secret_access_key: ''
+sakuracloud_api_token: ''
+sakuracloud_api_secret: ''
+netcup_customer_id: ''
+netcup_api_key: ''
+netcup_api_password: ''
+```
+
+## Example Configurations
+
+### http challenge
+
+```yaml
+email: [email protected]
+domains:
+  - home-assistant.io
+certfile: fullchain.pem
+keyfile: privkey.pem
+challenge: http
+dns: {}
+```
+
+### dns challenge
+
+```yaml
+email: [email protected]
+domains:
+  - home-assistant.io
+certfile: fullchain.pem
+keyfile: privkey.pem
+challenge: dns
+dns:
+  provider: dns-cloudflare
+  cloudflare_email: [email protected]
+  cloudflare_api_key: 31242lk3j4ljlfdwsjf0
+```
+
+### google dns challenge
+
+```yaml
+email: [email protected]
+domains:
+  - home-assistant.io
+certfile: fullchain.pem
+keyfile: privkey.pem
+challenge: dns
+dns:
+  provider: dns-google
+  google_creds: google.json
+```
+
+Please copy your credentials file "google.json" into the "share" shared folder on the Home Assistant host before starting the service.
+
+One way is to use the "Samba" add on to make the folder available via network or SSH Add-on.
+
+The credential file can be created and downloaded when creating the service user within the Google cloud.
+You can find additional information in regards to the required permissions in the "credentials" section here:
+
+<https://github.com/certbot/certbot/blob/master/certbot-dns-google/certbot_dns_google/__init__.py>
+
+### CloudFlare
+
+Previously, Cloudflare’s “Global API Key” was used for authentication, however this key can access the entire Cloudflare API for all domains in your account, meaning it could cause a lot of damage if leaked.
+
+Cloudflare’s newer API Tokens can be restricted to specific domains and operations, and are therefore now the recommended authentication option.
+
+However, due to some shortcomings in Cloudflare’s implementation of Tokens, Tokens created for Certbot currently require `Zone:Zone:Read` and `Zone:DNS:Edit` permissions for all zones in your account.
+
+Example credentials file using restricted API Token (recommended):
+```yaml
+dns:
+  provider: dns-cloudflare
+  cloudflare_api_token: 0123456789abcdef0123456789abcdef01234
+```
+
+Example credentials file using Global API Key (not recommended):
+```yaml
+dns:
+  provider: dns-cloudflare
+  cloudflare_email: [email protected]
+  cloudflare_api_key: 0123456789abcdef0123456789abcdef01234
+```
+
+
+## Certificate files
+
+The certificate files will be available within the "ssl" share after successful request of the certificates.
+
+By default other addons are referring to the correct path of the certificates.
+You can in addition find the files via the "samba" addon within the "ssl" share.
+
+## Supported DNS providers
+
+```txt
+dns-cloudflare
+dns-cloudxns
+dns-digitalocean
+dns-dnsimple
+dns-dnsmadeeasy
+dns-gehirn
+dns-google
+dns-linode
+dns-luadns
+dns-nsone
+dns-ovh
+dns-rfc2136
+dns-route53
+dns-sakuracloud
+dns-netcup
+```
+
+## 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]
+- Check out certbots page [certbot].
+
+In case you've found a bug, please [open an issue on our GitHub][issue].
+
+[discord]: https://discord.gg/c5DvZ4e
+[forum]: https://community.home-assistant.io
+[issue]: https://github.com/home-assistant/hassio-addons/issues
+[certbot]: https://certbot.eff.org
+[reddit]: https://reddit.com/r/homeassistant