218 lines
7.4 KiB
Markdown
218 lines
7.4 KiB
Markdown
# Bahmcloud Store – Full User Guide
|
||
|
||
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.
|
||
|
||
> BCS lets you install & manage custom integrations from **GitHub/GitLab/Gitea** and your own sources, with backups, restore, and version pinning.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
---
|
||
|
||
## Concepts
|
||
|
||
- **Sources**:
|
||
- **BCS Official** → entries from index (`store.yaml`) made and added from Bahmcloud
|
||
- **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 Bahmcloud 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)
|
||
- **Source** filter (All/BCS Official/HACS/Custom)
|
||
- **Category** filter (actually only Integrations are supported)
|
||
- **State-Filter** filter (All/Installed/Not installed/Update available/Custom repos)
|
||
- **Sort** (name (A-Z)/Updates first/Installed first)
|
||
- **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. (or use restart toggle in HomeAssistant Settings)
|
||
|
||
**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 in store.
|
||
2. Select **Restore…**.
|
||
3. Pick one of the **last backups** (up to retention limit). (Version details are showed in ())
|
||
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/Any other Git Hoster). 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)
|
||
|
||
**Add an custom repository**(typical flows):
|
||
- From the Store UI
|
||
1. If you start up Bahmcloud Store, you are on tab "Store"
|
||
2. Go to tab "Manage"
|
||
3. Add Repository URL (Example: ``https://git.bahmcloud.de/bahmcloud/bahmcloud_store``) and (optional) Name you want to show up (will be grabbed from GIT Repository)
|
||
4. Repository show up in Custom Repositories-list and in "Store" Tab, if available
|
||
|
||
**Remove an custom repository**(typical flows):
|
||
- From the Store UI
|
||
1. If you start up Bahmcloud Store, you are on tab "Store"
|
||
2. Go to tab "Manage"
|
||
3. Your repository you want to remove (if its custom) show up in the list
|
||
4. Press "Remove" Button to delete from Store (Attention: If you Remove installed Repository, you won´t be able to Uninstall from Store, you have to remove by your own (Delete Folder from ```config/custom_components/*```))
|
||
|
||
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 BCS-Official Repositories (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
|
||
|
||
---
|
||
|
||
## 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.
|
||
(You also can Install new version by selecting in Version tab)
|
||
- **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.
|