Full
This commit is contained in:
221
README_FULL.md
221
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/<domain>`
|
||||||
|
- **Backup**: BCS keeps pre‑update copies in `/config/.bcs_backups/<domain>/<timestamp>/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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/<domain>` 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/<domain>`.
|
||||||
|
- 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/<domain>/<timestamp>/
|
||||||
|
```
|
||||||
|
|
||||||
|
**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:<timestamp>` 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/<domain>/<timestamp>/`
|
||||||
|
- **Install path?** `/config/custom_components/<domain>`
|
||||||
|
- **Downgrade?** Yes, pick an older version and install.
|
||||||
|
- **Restart needed?** Yes, after install/update/restore.
|
||||||
|
|||||||
Reference in New Issue
Block a user