86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
---
|
|
title: "Presenting your addon"
|
|
---
|
|
|
|
If you decide to share your add-on to the public, paying attention to details is recommended. Of course, your add-on should have a proper name and description, but Home Assistant also gives you some other tools to present your add-on even nicer.
|
|
|
|
## Adding intro
|
|
|
|
This shows in add-on store and give the user a short instruction what the addon can.
|
|
|
|
This file containing the intro is usually referred to as the "README", which is generally published as the `README.md` file.
|
|
|
|
## Adding documentation
|
|
|
|
Good documentation helps the consumer of your add-on to understand its usage, explains configuration options, points users in the right direction in the case they have questions or issues, and contains the license under which the add-on was published.
|
|
|
|
This file containing the documentation is usually referred to as the "DOCS", which is generally published as the `DOCS.md` file.
|
|
|
|
## Add-on icon & logo
|
|
|
|
A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. Those images are used when showing your add-on in the Home Assistant Supervisor panel and which will significantly improve the visual representation of your add-on.
|
|
|
|
Requirements for the logo of your add-on:
|
|
|
|
- The logo must be in the Portable Network Graphics format (`.png`).
|
|
- The filename must be `logo.png`.
|
|
- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you seem fit for your add-on.
|
|
|
|
Requirements for the icon of your add-on:
|
|
|
|
- The icon must be in the Portable Network Graphics format (`.png`).
|
|
- The filename must be `icon.png`.
|
|
- The aspect ratio of the icon must be 1x1 (square).
|
|
- It is recommended to use an icon size of 128x128px.
|
|
|
|
## Keeping a changelog
|
|
|
|
It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on would see an upgrade notice and probably want to know what changes were made in the latest version.
|
|
|
|
A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of your add-on and is generally published as the `CHANGELOG.md` file.
|
|
|
|
If you are in need of a guide on keeping a changelog, we would recommend checking the [keep a changelog](http://keepachangelog.com) website. They have developed a standard that is used by many open source projects around the world.
|
|
|
|
## AppArmor
|
|
|
|
You can use own security profile for your add-on with AppArmor. By default it is enabled and uses the Docker default profile. Putting a `apparmor.txt` file into your add-on folder, will load that file as the primary profile instead. Use the config options to set the name of that profile.
|
|
|
|
apparmor.txt
|
|
```txt
|
|
#include <tunables/global>
|
|
|
|
profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) {
|
|
#include <abstractions/base>
|
|
|
|
# S6-Overlay
|
|
/bin/** ix,
|
|
/usr/bin/** ix,
|
|
/usr/lib/bashio/** ix,
|
|
/etc/s6/** ix,
|
|
/run/s6/** ix,
|
|
/etc/services.d/** rwix,
|
|
/etc/cont-init.d/** rwix,
|
|
/etc/cont-finish.d/** rwix,
|
|
|
|
# Data access
|
|
/data/** rw,
|
|
}
|
|
```
|
|
|
|
## Ingress
|
|
|
|
Ingress allow users to access the add-on web interface via the Home Assistant UI. Authentication is handled by Home Assistant, so neither the user nor the add-on developer will need to care about the security or port forwarding. Users love this feature, however it is not every time simple to implement for the add-on developer.
|
|
|
|
To add Ingress support, follow the following steps:
|
|
|
|
- The add-on will need to provide the web interface on port `8099`. Make sure that the add-on accepts only connections from `172.30.32.2` on that port and that the connections are treated as authenticated.
|
|
- Update add-on configuration and set `ingress: true`. Here it is also possible to configure the Ingress port by using the option `ingress_port: PORT_NUMBER` (default 8099).
|
|
- If you need to configure the application inside your add-on with the right path and port, query the add-on info API endpoint.
|
|
- If the application doesn't support relative paths or you can't set a base url, you can use nginx filter to replace the URL with correct path. Ingress adds a request header `X-Ingress-Path` that can be used.
|
|
|
|
Ingress API gateway supports the following:
|
|
|
|
- HTTP/1.x
|
|
- Streaming content
|
|
- Websockets
|