Update Hass.io developer informations (#219)

* Update Hass.io developer informations

* Add apparmor

docs/hassio_addon_communication.md

@@ -36,6 +36,8 @@ Add-ons can call some API commands without need set `hassio_api: true`:
 - `/discovery*`
 - `/info`
 
+***Note:*** Fore Home Assistant API access requirements look above.
+
 [hass-api]: https://www.home-assistant.io/developers/rest_api/
 [hass-websocket]: https://www.home-assistant.io/developers/websocket_api/
 [hassio-api]: https://github.com/home-assistant/hassio/blob/master/API.md

docs/hassio_addon_config.md

@@ -6,6 +6,7 @@ Each add-on is stored in a folder. The file structure looks like this:
 
 ```text
 addon_name/
+  apparmor.txt
   build.json
   CHANGELOG.md
   config.json
@@ -20,10 +21,12 @@ addon_name/
 
 As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things.
 
+All our Images have also [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons.
+
 When developing your script:
 
  - `/data` is a volume for persistent storage.
- - `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However, you might have to install `jq` as a separate package in your container (see `Dockerfile` below).
+ - `/data/options.json` contains the user configuration. You can use bashio or `jq` inside your shell script to parse this data.
 
 ```bash
 CONFIG_PATH=/data/options.json
@@ -37,9 +40,11 @@ So if your `options` contain
 ```
 then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards.
 
+[bashio]: https://github.com/hassio-addons/bashio
+
 ## Add-on Docker file
 
-All add-ons are based on Alpine Linux 3.6. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images.
+All add-ons are based on latest Alpine Linux. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images.
 
 ```
 ARG BUILD_FROM
@@ -117,6 +122,7 @@ The config for an add-on is stored in `config.json`.
 | host_pid | bool | no | Default False. Allow to run container on host PID namespace. Work only for not protected add-ons.
 | devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
 | auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on.
+| homeassistant | string | no | Pin a minimun required Home Assistant version for such Add-on. Value is a version string like `0.91.2`.
 | hassio_role | str | no | Default `default`. Role based access to Hass.io API. Available: `default`, `homeassistant`, `backup`, `manager`, `admin`.
 | hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
 | homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://hassio/homeassistant/api`.
@@ -140,6 +146,10 @@ The config for an add-on is stored in `config.json`.
 | discovery | list | no | A list of services they this Add-on allow to provide for Home Assistant. Currently supported: `mqtt`
 | services | list | no | A list of services they will be provided or consumed with this Add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly).
 | auth_api | bool | no | Allow access to Home Assistent user backend.
+| ingress | bool | no | Enable the ingress feature for the Add-on
+| ingress_port | integer | no | Default `8099`. For Add-ons they run on host network, you can use `0` and read the port later on API.
+| ingress_entry | string | no | Modify the URL entry point from `/`.
+
 
 ### Options / Schema
 
@@ -207,3 +217,7 @@ You need this only, if you not use the default images or need additionals things
 | build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
 | squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that!
 | args | no | Allow to set additional Docker build arguments as a dictionary.
+
+We provide a set of [Base-Images][hassio-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific Image tag, feel free to pin this requirements for you build with `build_from` option.
+
+[hassio-base]: https://github.com/home-assistant/hassio-base

docs/hassio_addon_index.md

@@ -15,3 +15,14 @@ Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.
 1. [Presentation](hassio_addon_presentation.md)
 1. [Repositories](hassio_addon_repository.md)
 1. [Security](hassio_addon_security.md)
+
+
+Usefully links:
+
+* [Hass.io Supervisor](https://github.com/home-assistant/hassio)
+* [Hass.io Core Add-ons](https://github.com/home-assistant/hassio-addons)
+* [Hass.io Build environment](https://github.com/home-assistant/hassio-build)
+* [Hass.io base images](https://github.com/home-assistant/hassio-base)
+* [Hass.io community Add-ons](https://github.com/hassio-addons)
+* [HassOS embedded Linux](https://github.com/home-assistant/hassos)
+* [Home Assistant Dockerfile](https://github.com/home-assistant/hassio-homeassistant)

docs/hassio_addon_presentation.md

@@ -44,3 +44,16 @@ In future versions of Hass.io, the `CHANGELOG.md` file will be displayed in the
 ## AppArmor
 
 You can use own security profile for you Add-on with AppArmor. Default it is enabled and use the Docker default profile. Put `apparmor.txt` file into your Add-on folder and it will load this file as primary profile. Use the config options to set the name of that profile.
+
+## Ingress
+
+Ingress allow to reach the Add-on web interface inside Home Assistant UI. User and Add-on developer need not care about the security or port forwarding. This feature would be loved by user and is not every time simple to implement for Add-on developer.
+
+The Add-on need provide the webinterface on port `8099`. This is configurable over the Add-on config, like a lot more. Make sure that the Add-on accept only connection from `172.30.32.2` on that port and he don't need provide any user login mechanics on this port. Now set `ingress: true` on Add-on configuration. You can read all details around path/port from your Add-on info API endpoint if you need this details to configure the web app.
+
+If your web interface don't support relative path or you can't set a base url, you can use nginx filter to replace the URL with correct path.
+
+Ingress API gateway support:
+ * HTTP/1.x
+ * Streaming content
+ * Websockets

docs/hassio_addon_security.md

@@ -30,3 +30,12 @@ As a developer, follow the following best practices to make your add-on secure:
 - Create an AppArmor profile
 - Map folders read only if you don't need write access
 - If you need any API access, make sure you that you not grant to highest permission if you don't need it
+
+## Use Home Assistant User backend
+
+Instead to allow users to set new login credential in plain text config, use the Home Assistant [Auth backend][hassio-api-auth]. You can enable the access to API with `hassio_auth: true`. Now you are able to send the login credential to auth backend and validate it again Home Assistant.
+
+We have some sample and helper around that system collected in a [GitHub repository][hassio-auth]. Feel free to copy past it or provide your usefully scripts.
+
+[hassio-auth]: https://github.com/home-assistant/hassio-auth
+[hassio-api-auth]: https://github.com/home-assistant/hassio/blob/dev/API.md#auth--sso-api

docs/hassio_addon_testing.md

@@ -6,6 +6,12 @@ The fastest way to develop add-ons is by adding them to your local add-on reposi
 
 Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). Without `image` inside local add-ons repository it to be built on the device.
 
+The [Community Add-on][hassio-vagrant] repository create a vagrant based development system. This Vagrant virtual machine allows you to test and play with Hass.io and Home Assistant, and is a great environment for add-on developers
+
+[Samba add-on]: https://www.home-assistant.io/addons/samba/
+[SSH add-on]: https://www.home-assistant.io/addons/ssh/
+[hassio-vagrant]: https://github.com/hassio-addons/hassio-vagrant
+
 ## Local build
 
 You can build and try the addon on your developer machine also. Move all addon stuff into a temp folder. If you use `FROM $BUILD_FROM` you need set a base image with build args. Normally you can use follow base images:
@@ -24,6 +30,3 @@ Create a new folder for data and add a test _options.json_ file. After that you
 ## Logs
 
 All stdout and stderr are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.
-
-[Samba add-on]: https://www.home-assistant.io/addons/samba/
-[SSH add-on]: https://www.home-assistant.io/addons/ssh/

docs/hassio_hass.md

@@ -14,6 +14,11 @@ To develop for the frontend, we're going to need API access to the supervisor.
 - Add our developer Add-on repository: https://github.com/home-assistant/hassio-addons-development
 - Install the Add-on "Remote API proxy"
 
+For some API commands you need explicit the Home Assistant API token, but 99% of the functionality work with `Remote API proxy`. This token change some times but you can read the current legal token on host system with:
+```sh
+$ docker inspect homeassistant | grep HASSIO_TOKEN
+```
+
  ## Having Home Assistant connect to remote Hass.io
 
  The connection with the supervisor is hidden inside the host and is only accessible from applications running on the host. So to make it accessible for our Home Assistant instance, we will need to route the connection to our computer running Home Assistant. We're going to do this by forwarding the API with "Remote API proxy" Add-on.