mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-10-25 16:30:11 +01:00
Compare commits
10 Commits
e11182e837
...
copilot/fi
| Author | SHA1 | Date | |
|---|---|---|---|
|
f07859fbbb | ||
|
|
30e78aaa70 | ||
|
|
749426fe0d | ||
|
|
d8f32d838e | ||
|
|
614ff9cd78 | ||
|
|
07b8c5548d | ||
|
|
f3b0d4e9cc | ||
|
|
93fa7fe2d6 | ||
|
|
79c16cffd7 | ||
|
|
74fbadb8b1 |
148
CLAUDE.md
Normal file
148
CLAUDE.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This is a Home Assistant add-on repository containing 120+ Docker-based add-ons for the Home Assistant Supervisor. Each add-on is a self-contained directory with a Dockerfile, config schema, and S6-overlay init scripts. The repository uses GitHub Actions for CI/CD, linting, and automated upstream version tracking.
|
||||
|
||||
## Add-On Directory Structure
|
||||
|
||||
Most add-ons follow this common layout, though exceptions exist (e.g. some archived add-ons use `config.json` instead of `config.yaml`, some add-ons have `build.yaml` instead of `build.json` or no build file at all, and not every add-on includes a `rootfs/` tree):
|
||||
|
||||
```
|
||||
addon_name/
|
||||
├── config.yaml # HA add-on metadata, schema, ports, maps
|
||||
├── build.json # Base Docker images per architecture (may be build.yaml, or absent)
|
||||
├── Dockerfile # Multi-stage build (always uses shared .templates/ scripts)
|
||||
├── updater.json # Upstream release tracking; required to enable automatic updates
|
||||
├── CHANGELOG.md # Required; must be updated on every PR
|
||||
└── rootfs/ # Optional; absent in some add-ons
|
||||
└── etc/
|
||||
├── cont-init.d/ # S6-overlay init scripts (numbered, run in order)
|
||||
└── services.d/ # S6-overlay supervised services (some add-ons use
|
||||
# s6-overlay v3 layout at etc/s6-overlay/s6-rc.d/ instead)
|
||||
```
|
||||
|
||||
## Dockerfile Convention
|
||||
|
||||
Most Dockerfiles follow this 6-section pattern (some add-ons deviate slightly, e.g. using a pinned upstream image directly instead of `ARG BUILD_FROM`):
|
||||
|
||||
1. **Build Image** – `ARG BUILD_FROM` + `FROM ${BUILD_FROM}`
|
||||
2. **Modify Image** – S6 env vars, LSIO modifications via `ha_lsio.sh`
|
||||
3. **Install Apps** – Copy `rootfs/`, download modules, install packages
|
||||
4. **Entrypoint** – Set `S6_STAGE2_HOOK=/ha_entrypoint.sh`
|
||||
5. **Labels** – Standard OCI + HA labels from build args
|
||||
6. **Healthcheck** – curl-based check suppressed from nginx/apache logs
|
||||
|
||||
Shared build-time scripts are pulled from `.templates/` at build time:
|
||||
- `ha_automodules.sh` – Downloads module scripts listed in `ARG MODULES=`
|
||||
- `ha_autoapps.sh` – Installs packages listed in `ENV PACKAGES=`
|
||||
- `ha_entrypoint.sh` – S6 stage-2 hook; launches the cont-init stack at container start
|
||||
- `ha_lsio.sh` – Patches LinuxServer.io base images for HA compatibility
|
||||
- `bashio-standalone.sh` – Bashio library for scripts outside Supervisor context
|
||||
|
||||
The `ARG MODULES=` line lists template scripts to download at build time (e.g., `00-banner.sh 01-custom_script.sh 00-smb_mounts.sh`). Commonly-used modules in `.templates/` (not exhaustive):
|
||||
- `00-global_var.sh` – Initialize global env vars from HA options
|
||||
- `00-local_mounts.sh` – Mount local disks (localdisks option)
|
||||
- `00-smb_mounts.sh` – SMB/CIFS network mount support
|
||||
- `01-config_yaml.sh` – Map HA options → app's `config.yaml`
|
||||
- `01-custom_script.sh` – Run user-provided custom scripts
|
||||
- `90-disable_ingress.sh` – Allow disabling HA ingress
|
||||
- `90-dns_set.sh` – Configure custom DNS
|
||||
- `91-universal_graphic_drivers.sh` – GPU driver detection
|
||||
- `19-json_repair.sh` – Validate/repair JSON config files
|
||||
|
||||
## config.yaml Schema
|
||||
|
||||
Key fields in every add-on's `config.yaml`:
|
||||
|
||||
```yaml
|
||||
arch: [aarch64, amd64]
|
||||
image: ghcr.io/alexbelgium/{slug}-{arch}
|
||||
version: "X.Y.Z" # upstream version (format varies; see Versioning section)
|
||||
ingress: true/false
|
||||
ingress_port: 8000
|
||||
map:
|
||||
- addon_config:rw # /addon_configs/<hostname>/
|
||||
- share:rw
|
||||
- media:rw
|
||||
- ssl
|
||||
schema:
|
||||
env_vars: # Allows arbitrary env var passthrough
|
||||
- name: match(^[A-Za-z0-9_]+$)
|
||||
value: str?
|
||||
PUID: int
|
||||
PGID: int
|
||||
TZ: str?
|
||||
networkdisks: str? # SMB mounts
|
||||
localdisks: str? # Local disk mounts
|
||||
```
|
||||
|
||||
The `env_vars` schema key enables the env-var passthrough mechanism. At runtime the `00-global_var.sh` cont-init module reads `/data/options.json` and exports each key as an environment variable (writing to `/.env` and `/etc/environment`). `ha_entrypoint.sh` is the S6 stage-2 hook that launches the cont-init stack but does not itself perform the JSON-to-env conversion.
|
||||
|
||||
## Versioning
|
||||
|
||||
Add-on versions in `config.yaml` closely follow the upstream release tag and do not conform to a single fixed format. Common patterns include:
|
||||
|
||||
- `X.Y.Z` – plain upstream semver (e.g. `0.137.0`)
|
||||
- `X.Y.Z-N` – upstream version with a local patch counter (e.g. `0.6.26-2`)
|
||||
- LSIO-style tags (e.g. `1.43.1.10611-1e34174b1-ls301`)
|
||||
- Date-based versions (e.g. `2026.02.28`)
|
||||
- Nightly builds (e.g. `nightly-20260321-397`)
|
||||
|
||||
When an upstream version is bumped, update `version` in `config.yaml`. If the add-on's `Dockerfile` contains an `ARG BUILD_UPSTREAM` line, update that value too — it is the canonical place that records the upstream version at build time (it is **not** stored in `build.json`/`build.yaml`). Some add-ons do not use `BUILD_UPSTREAM` at all. The `updater.json` file tracks which upstream source/repo to monitor and records the last seen version.
|
||||
|
||||
## updater.json Format
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "github", // github|dockerhub|pip|gitlab|bitbucket|helm_chart|...
|
||||
"upstream_repo": "owner/repo",
|
||||
"upstream_version": "1.2.3", // auto-populated by addons_updater
|
||||
"slug": "addon_slug",
|
||||
"last_update": "2025-01-01",
|
||||
"github_beta": false,
|
||||
"github_fulltag": false, // true = keep "v3.0.1-ls67", false = strip to "3.0.1"
|
||||
"github_tagfilter": "", // require this text in release tag
|
||||
"github_exclude": "", // exclude releases containing this text
|
||||
"paused": false
|
||||
}
|
||||
```
|
||||
|
||||
## CI/CD Workflows
|
||||
|
||||
**On push to master** (`onpush_builder.yaml`): Detects changed add-ons by watching `config.*` files, then sanitizes text files (Unicode spaces → ASCII, CRLF → LF) and restores shell script permissions. Auto-commits fixes with `[nobuild]` to skip rebuild loop.
|
||||
|
||||
**On PR** (`onpr_check-pr.yaml`): Validates CHANGELOG.md was updated, runs HA addon-linter, and tests Docker build for all changed add-ons.
|
||||
|
||||
**Weekly** (`lint.yml`): Runs Super-Linter across the repo, fixes shell formatting with shfmt (4-space indent), opens PRs for automated fixes.
|
||||
|
||||
**Weekly** (`weekly_addons_updater`): Runs the `addons_updater` container to bump add-on versions to match upstream.
|
||||
|
||||
Adding `[nobuild]` anywhere in a commit message skips the builder workflow.
|
||||
|
||||
## Linting Rules
|
||||
|
||||
| Tool | Config | Key ignores |
|
||||
|------|--------|------------|
|
||||
| Hadolint | `.hadolint.yaml` | DL3002, DL3006-9, DL3018 (no pinning required) |
|
||||
| ShellCheck | `.shellcheckrc` | SC2002 |
|
||||
| Markdownlint | `.markdownlint.yaml` | MD013 (line length), MD025, MD033, MD041 |
|
||||
| shfmt | (CI enforced) | 4-space indent |
|
||||
|
||||
## PR Requirements
|
||||
|
||||
1. Update `CHANGELOG.md` in every changed add-on (CI validates this).
|
||||
2. Bump `version` in `config.yaml`.
|
||||
3. All linting must pass (Hadolint, ShellCheck, Markdownlint, HA addon-linter).
|
||||
4. Docker build must succeed for all declared architectures.
|
||||
|
||||
## S6-Overlay Init Script Naming
|
||||
|
||||
Scripts in `rootfs/etc/cont-init.d/` run in lexicographic order. Common numbering conventions (many add-ons use other prefixes too):
|
||||
- `20-*` – Directory/folder setup
|
||||
- `32-*` – Nginx ingress configuration (e.g. `32-nginx_ingress.sh`)
|
||||
- `80-*` – Application configuration
|
||||
- `90-*` – Misc pre-startup tasks (ssl, vpn, custom run)
|
||||
- `99-*` – Final startup / launch
|
||||
@@ -112,12 +112,13 @@ If you want to do add the repository manually, please follow the procedure highl
|
||||
![smb][smb-badge]
|
||||
![localdisks][localdisks-badge]
|
||||
|
||||
✓ [Bazarr NAS](bazarr/) : Companion application to Sonarr and Radarr to download subtitles
|
||||
✓  [Bazarr NAS](bazarr/) : Companion application to Sonarr and Radarr to download subtitles
|
||||
|
||||
  
|
||||
|
||||
![aarch64][aarch64-badge]
|
||||
![amd64][amd64-badge]
|
||||
![ingress][ingress-badge]
|
||||
![smb][smb-badge]
|
||||
![localdisks][localdisks-badge]
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
|
||||
## 0.6.6 (2026-04-21)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
|
||||
## 0.6.4 (2026-04-18)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.6.3-3 (2026-04-17)
|
||||
@@ -13,7 +16,7 @@
|
||||
- Removes incidental brittleness from byte-level `sub_filter` matches in minified JS bundles (the old `/stream/` rule had inadvertently double-prefixed the literal `api.get("/stream/config")` string).
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
|
||||
## 0.6.2-2 (11-04-2026)
|
||||
## 0.6.2-2 (2026-04-11)
|
||||
- Minor bugs fixed
|
||||
|
||||
## 0.6.2 (2026-04-11)
|
||||
@@ -39,21 +42,21 @@
|
||||
|
||||
## 0.5.6 (2026-03-07)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.5.5-2 (04-03-2026)
|
||||
## 0.5.5-2 (2026-03-04)
|
||||
- Minor bugs fixed
|
||||
|
||||
## 0.5.5 (2026-03-02)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.5.4-3 (26-02-2026)
|
||||
## 0.5.4-3 (2026-02-26)
|
||||
- Minor bugs fixed
|
||||
## 0.5.4-2 (23-02-2026)
|
||||
## 0.5.4-2 (2026-02-23)
|
||||
- Fix Icecast service failing to connect to PulseAudio on HAOS by respecting PULSE_SERVER env var and setting up socket symlink and auth cookie for icecast2 user
|
||||
|
||||
## 0.5.4 (2026-02-21)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.5.0-6 (15-02-2026)
|
||||
## 0.5.0-6 (2026-02-15)
|
||||
- Minor bugs fixed
|
||||
## 0.5.0-5 (15-02-2026)
|
||||
## 0.5.0-5 (2026-02-15)
|
||||
- Minor bugs fixed
|
||||
## 0.5.0-4 (2026-02-15)
|
||||
- Disable nginx service when ingress is not active
|
||||
@@ -69,31 +72,20 @@
|
||||
|
||||
## 0.4.0 (2026-02-07)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.3.2-6 (01-02-2026)
|
||||
## 0.3.2-6 (2026-02-01)
|
||||
- Minor bugs fixed
|
||||
## 0.3.2-5 (01-02-2026)
|
||||
## 0.3.2-5 (2026-02-01)
|
||||
- Minor bugs fixed
|
||||
## 0.3.2-4 (31-01-2026)
|
||||
## 0.3.2-4 (2026-01-31)
|
||||
- Minor bugs fixed
|
||||
## 0.3.2-2 (31-01-2026)
|
||||
## 0.3.2-2 (2026-01-31)
|
||||
- Minor bugs fixed
|
||||
|
||||
## 0.3.2-3 (2026-01-30)
|
||||
- Build frontend with /birdnet/ base path and serve under /birdnet/ for ingress compatibility.
|
||||
## 0.3.2 (2026-01-30)
|
||||
- Update to latest version from Suncuss/BirdNET-PiPy (changelog : https://github.com/Suncuss/BirdNET-PiPy/releases)
|
||||
## 0.6.6 (30-01-2026)
|
||||
- Minor bugs fixed
|
||||
## 0.6.5 (30-01-2026)
|
||||
- Minor bugs fixed
|
||||
## 0.6.3 (29-01-2026)
|
||||
- Minor bugs fixed
|
||||
## 0.6.2 (29-01-2026)
|
||||
- Use upstream nginx.conf and generate ingress config at startup
|
||||
## 0.6.1 (29-01-2026)
|
||||
- Minor bugs fixed
|
||||
## 0.2 (29-01-2026)
|
||||
- Minor bugs fixed
|
||||
|
||||
# Changelog
|
||||
|
||||
## 0.1.0
|
||||
|
||||
@@ -96,4 +96,4 @@ schema:
|
||||
ssl: bool?
|
||||
slug: birdnet-pipy
|
||||
url: https://github.com/alexbelgium/hassio-addons/tree/master/birdnet-pipy
|
||||
version: "0.6.4"
|
||||
version: "0.6.6"
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"last_update": "2026-04-18",
|
||||
"last_update": "2026-04-21",
|
||||
"repository": "alexbelgium/hassio-addons",
|
||||
"slug": "birdnet-pipy",
|
||||
"source": "github",
|
||||
"upstream_repo": "Suncuss/BirdNET-PiPy",
|
||||
"upstream_version": "0.6.4"
|
||||
"upstream_version": "0.6.6"
|
||||
}
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
## 3.2.0 (21-04-2026)
|
||||
- Minor bugs fixed
|
||||
## 3.1.0-4 (14-04-2026)
|
||||
- Minor bugs fixed
|
||||
## 3.1.0-3 (14-04-2026)
|
||||
|
||||
@@ -95,4 +95,4 @@ schema:
|
||||
slug: seerr
|
||||
udev: true
|
||||
url: https://github.com/alexbelgium/hassio-addons/tree/master/seerr
|
||||
version: "3.1.0-4"
|
||||
version: "3.2.0"
|
||||
|
||||
Reference in New Issue
Block a user