From 113c951028068a9a486a01b06197f0e93aa015e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Bachmann?= Date: Mon, 19 Jan 2026 08:09:48 +0000 Subject: [PATCH] Full --- README_FULL.md | 221 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 209 insertions(+), 12 deletions(-) diff --git a/README_FULL.md b/README_FULL.md index d8fd0e2..f69601c 100644 --- a/README_FULL.md +++ b/README_FULL.md @@ -1,19 +1,216 @@ -# Bahmcloud Store – Full Technical Documentation +# Bahmcloud Store – Full User Guide -Complete technical documentation. +This guide explains **all features** of Bahmcloud Store (BCS) for Home Assistant. +It is written for users and admins who want a complete, practical reference. -## Features +> TL;DR: BCS lets you install & manage custom integrations from **GitHub/GitLab/Gitea** and your own sources, with backups, restore, and version pinning. -- Provider-neutral store -- UI panel -- Install / Update / Restore -- Background cache -- Update entities +--- -## Index +## Contents +- Concepts +- Sources (BCS / HACS / Custom) +- UI Overview +- Finding Integrations +- Installing +- Selecting Versions / Downgrading +- Updating +- Uninstalling +- Backups & Restore +- Custom Repositories +- HACS Repositories +- Update Entities in Home Assistant +- Background Caching & Performance +- Restart Required +- Troubleshooting +- FAQ -store.yaml defines repositories and refresh interval. +--- -## API +## Concepts -/api/bcs endpoints for store control. +- **Index (`store.yaml`)**: your curated list of repositories. Example: + ```yaml + refresh_seconds: 300 + repos: + - name: Easy Proxmox + url: https://git.bahmcloud.de/bahmcloud/easy_proxmox + category: Infrastructure + ``` +- **Sources**: + - **BCS Official** → entries from your index (`store.yaml`) + - **HACS** → official HACS integrations list (toggleable) + - **Custom** → manual entries you add locally +- **Install location**: `/config/custom_components/` +- **Backup**: BCS keeps pre‑update copies in `/config/.bcs_backups///` + +--- + +## Sources (BCS / HACS / Custom) + +Each repository card shows a **source badge**: +- **BCS Official** – from your index +- **HACS** – from HACS official list (enable with the toggle) +- **Custom** – added by you + +You can **filter by source** with the **Source** dropdown (All / BCS Official / HACS / Custom). + +--- + +## UI Overview + +Top bar: +- **Search** (name/description) +- **Category** filter +- **Source** filter (BCS/HACS/Custom) +- **Sort** (name, updated, etc.) +- **HACS official** toggle (on/off) + +Repository card: +- Name, description, badges (source, installed/update), category +- Buttons: **Install / Update / Uninstall** +- **Readme** expandable +- **Open** to see details (available versions, metadata) + +--- + +## Finding Integrations + +1. Use **Search** to filter by keywords. +2. Combine with **Category** and **Source**. +3. Sort to surface desired results. + +Descriptions and latest versions are filled progressively by a background process; opening a repo loads details on demand. + +--- + +## Installing + +1. Open a repository. +2. Optionally select **Install version** (default: **Latest**). +3. Click **Install** and wait for confirmation. +4. Follow the **Restart required** prompt. + +**What happens internally** +- BCS downloads the repository ZIP for the selected version (release/tag/branch). +- It extracts all integrations found under `custom_components/` and deploys them. +- It saves the **installed version (ref)** to track updates reliably, even if the repo’s own `manifest.json` is wrong/outdated. + +--- + +## Selecting Versions / Downgrading + +- Use the **Install version** dropdown in the detail view. +- Choose **Latest** or a previous **release/tag**. +- Installing a chosen ref **pins** the integration to that ref (no surprise updates). +- You can upgrade again later by selecting **Latest** and clicking **Update**. + +--- + +## Updating + +- The **Update** button appears when `latest_version` differs from your **installed version (ref)**. +- Updates are also available via **Home Assistant → Settings → Updates** (native Update entity). +- Clicking **Update** runs the same safe pipeline as **Install** (with backup). + +**Tip:** Opening a repository detail view forces an immediate check for the latest version for that repo. + +--- + +## Uninstalling + +- Click **Uninstall** on the repository. +- BCS removes the integration folders under `custom_components/`. +- The installed state is cleared in the Store. +- Restart Home Assistant if prompted. + +--- + +## Backups & Restore + +Before an update/install over existing files, BCS creates a backup: + +``` +/config/.bcs_backups/// +``` + +**Restore**: +1. Open the repository. +2. Select **Restore…**. +3. Pick one of the **last backups** (up to retention limit). +4. Confirm – BCS restores files and reconciles installed version to the restored ref. +5. Restart Home Assistant if prompted. + +If the old backup lacks metadata, BCS best‑effort derives the installed version from the backup’s `manifest.json`, or marks the ref as `restored:` so updates remain possible. + +--- + +## Custom Repositories + +You can add any public repository (GitHub/GitLab/Gitea). BCS will attempt to detect: +- provider & default branch +- latest version (release/tag/atom) +- repo metadata (prefer `bcs.yaml`, fallback `hacs.json/hacs.yaml`) +- readme (common filenames) + +**To add a custom repo** (typical flows): +- From the Store UI (if available), or +- via API (see developer docs), or +- by editing your local custom repo storage (advanced). + +Custom repos get the **Custom** badge and can be filtered via **Source**. + +--- + +## HACS Repositories + +Enable the **HACS official** toggle to include official HACS integrations. + +- BCS downloads the HACS integration list and maps **human‑readable names/descriptions** from HACS metadata. +- HACS entries are **not** part of your `store.yaml` (avoid duplicate entries). + +With many HACS repos, metadata loads in the background; names/descriptions appear progressively and are cached. + +--- + +## Update Entities in Home Assistant + +BCS exposes update entities for installed repos: +- Found under **Settings → Updates** +- Clicking **Install** triggers BCS update pipeline +- Shows **installed** and **latest** versions (BCS ref logic) + +--- + +## Background Caching & Performance + +- **Fast initial list**: index + local cache only +- **Background enrichment**: provider info, latest version, metadata, description, readme (best effort) +- **On‑demand**: opening a repo triggers immediate enrichment; data is **persisted** to cache +- **Persistent cache**: survives HA restarts; speeds up subsequent runs +- **Refresh**: immediately rechecks installed repos and key metadata + +If you enable HACS, keep your `store.yaml` light and curated. + +--- + +## Restart Required + +After install, update, or restore, BCS raises a **Restart required** item in Home Assistant (Repairs). You can restart directly from there. + +--- + +## Troubleshooting + +- **New release but no update**: Open the repo detail once; ensure it’s a **release/tag** (commits alone don’t change the ref). +- **Descriptions/Latest missing**: Wait for background enrichment or open the repo detail (forces enrichment). Cached afterwards. +- **Slow startup**: BCS schedules heavy work after HA started. Keep indexes reasonable. + +--- + +## FAQ + +- **Backups path?** `/config/.bcs_backups///` +- **Install path?** `/config/custom_components/` +- **Downgrade?** Yes, pick an older version and install. +- **Restart needed?** Yes, after install/update/restore.