Skip to content

Commit b944967

Browse files
acockburnacockburn
authored
Merge pull request #2503 from AppDaemon/addon-docs
added a doc page for the add-on
2 parents cdc3ce6 + 2d5e603 commit b944967

File tree

4 files changed

+134
-0
lines changed

4 files changed

+134
-0
lines changed

‎docs/ADDON.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# AppDaemon Add-on
2+
3+
The [AppDaemon python package] and the [AppDaemon Add-on for Home Assistant] (maintained by [Frenck]) have no official relationship. They have different versions and release schedules, but are both commonly run using Docker containers. The AppDaemon project provides a [Docker container], and the add-on uses another one that includes some things to help it integrate with Home Assistant's Supervisor.
4+
5+
[AppDaemon python package]: https://pypi.org/project/appdaemon/
6+
[AppDaemon Add-on for Home Assistant]: https://github.com/hassio-addons/addon-appdaemon
7+
[Frenck]: https://github.com/frenck
8+
[Docker container]: https://hub.docker.com/r/acockburn/appdaemon
9+
10+
:::{tip}
11+
[Install AppDaemon Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_appdaemon&repository_url=https%3A%2F%2Fgithub.com%2Fhassio-addons%2Frepository)
12+
:::
13+
14+
:::{note}
15+
- **Add-on Repository**: [hassio-addons/addon-appdaemon](https://github.com/hassio-addons/addon-appdaemon)
16+
- **AppDaemon Repository**: [AppDaemon/appdaemon](https://github.com/AppDaemon/appdaemon)
17+
:::
18+
19+
## Workflow
20+
21+
An easy way to work with the AppDaemon config files is to expose them with a [Samba] share, which uses [smb] to make folders accessible across a network. This is an old, well-established standard that works really well across platforms. The Samba add-on makes the AppDaemon config folder accessible at `addon_configs/a0d7b954_appdaemon`. That share can be mounted on your local system as a network drive where it can be accessed with an IDE like [VSCode] or [PyCharm].
22+
23+
See [this section](https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-samba-add-on) of the Home Assistant docs for more information about accessing samba shares.
24+
25+
[Samba]: https://www.samba.org/
26+
[smb]: https://en.wikipedia.org/wiki/Server_Message_Block
27+
[VSCode]: https://code.visualstudio.com/
28+
[PyCharm]: https://www.jetbrains.com/pycharm/
29+
30+
:::{tip}
31+
[Install Samba Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) [(configuration docs)](https://github.com/home-assistant/addons/blob/master/samba/DOCS.md)
32+
:::
33+
34+
35+
36+
## Paths
37+
38+
| Name | Inside Container | Samba | Host |
39+
| --------------------- | ---------------- | --------------------------------- | ----------------------------------------------------- |
40+
| Home Assistant config | /homeassistant | /config | /mnt/data/supervisor/homeassistant |
41+
| AppDaemon config | /config | /addon_configs/a0d7b954_appdaemon | /mnt/data/supervisor/addon_configs/a0d7b954_appdaemon |
42+
| Home Assistant Media | /media | /media | /mnt/data/supervisor/media |
43+
| Home Assistant Share | /share | /share | /mnt/data/supervisor/share |
44+
45+
## Config
46+
47+
### Token
48+
49+
The authentication token for the Hass plugin is automatically provided by the Hass Supervisor using the `SUPERVISOR_TOKEN` environment variable.
50+
51+
### System Packages
52+
53+
System packages are installed into the container environment using [apk] before AppDaemon is launched. Anything from the [Alpine Package Index] can be used.
54+
55+
For example, to install [pandas]:
56+
```
57+
py3-pandas
58+
```
59+
60+
[pandas]: https://pandas.pydata.org/
61+
[apk]: https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper
62+
[Alpine Package Index]: https://pkgs.alpinelinux.org/packages?branch=v3.22
63+
64+
:::{tip}
65+
Many python packages can be installed this way, which is much faster and more reliable than using pip. The packages usually have a <a href="https://pkgs.alpinelinux.org/packages?name=py3*&branch=v3.22"><code>py3-*</code>prefix</a>.
66+
:::
67+
68+
### Python Packages
69+
70+
Python packages are installed into the container environment using pip before AppDaemon is launched. Any package on PyPI can be used. Pip also [supports targeting VCS systems](https://pip.pypa.io/en/stable/topics/vcs-support/#supported-vcs), so any python packages on GitHub can be installed directly in several ways:
71+
72+
- `git+<github_url>@<branch>`
73+
- `git+<github_url>@<short commit hash>`
74+
- `<github_url>/archive/refs/heads/<long commit hash>.zip`
75+
76+
![appdaemon add-on config](./images/appdaemon_add-on_cfg.png)
77+
78+
:::{tip}
79+
The add-on will use the version of AppDaemon installed from GitHub in the example screenshot above. This makes it easy to control which version of AppDaemon the add-on uses.
80+
81+
- `git+https://github.com/AppDaemon/appdaemon@dev`
82+
- `git+https://github.com/AppDaemon/[email protected]`
83+
- `git+https://github.com/AppDaemon/appdaemon@beaa161`
84+
85+
:::
86+
87+
88+
## Docker Mechanics
89+
90+
This section shows some of how the AppDaemon add-on container works in the supervised environment of [Hass OS] and is just for informational purposes. It uses the [Advanced SSH & Web Terminal Add-on] to inspect the Docker container.
91+
92+
[Hass OS]: https://github.com/home-assistant/operating-system
93+
[Advanced SSH & Web Terminal Add-on]: https://github.com/hassio-addons/addon-ssh/tree/main
94+
95+
:::{tip}
96+
[Install Advanced SSH & Web Terminal Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_ssh&repository_url=https%3A%2F%2Fgithub.com%2Fhassio-addons%2Frepository)
97+
:::
98+
99+
:::{warning}
100+
Protection mode has to be disabled for the SSH add-on for the following instructions to work. It's recommended to only disable it temporarily. Proceed carefully and at your own risk.
101+
:::
102+
103+
**Check the status of the AppDaemon container**
104+
105+
```zsh
106+
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" | grep appdaemon
107+
```
108+
109+
**Check the AppDaemon container logs**
110+
```zsh
111+
docker logs --tail 10 addon_a0d7b954_appdaemon
112+
```
113+
114+
**Enter the AppDaemon container**
115+
```zsh
116+
docker exec -it addon_a0d7b954_appdaemon /bin/bash
117+
```
118+
119+
**Show volume mounts from the AppDaemon container**
120+
```zsh
121+
docker inspect --format='{{json .Mounts}}' addon_a0d7b954_appdaemon | \
122+
jq -r '.[] | select(.Type == "bind") | [.Destination, .Source] | @tsv'
123+
```
124+
125+
**View installed Python packages**
126+
```zsh
127+
docker exec addon_a0d7b954_appdaemon pip list
128+
```

‎docs/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@
3535

3636
copybutton_exclude = '.linenos, .gp'
3737

38+
# -- MyST configuration ------------------------------------------------------
39+
myst_enable_extensions = [
40+
"colon_fence",
41+
]
42+
3843
templates_path = ["_templates"]
3944
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
4045

‎docs/images/appdaemon_add-on_cfg.png‎

65.4 KB
Loading

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ Contents:
6363
INSTALL
6464
CONFIGURE
6565
DOCKER_TUTORIAL
66+
ADDON
6667
HASS_TUTORIAL
6768
APPGUIDE
6869
COMMUNITY_TUTORIALS

0 commit comments

Comments
 (0)