bahmcloud/bahmcloud_store
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity

Add blueprint support and refresh documentation

Browse Source
This commit is contained in:
René Bachmann
2026-03-23 16:42:52 +01:00
parent 48f8ef6265
commit a55281938c
7 changed files with 415 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
README_FULL.md
View File

@@ -1,27 +1,30 @@
# Bahmcloud Store – Full User Guide
# 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.
This guide explains the current feature set of Bahmcloud Store (BCS) for Home Assistant.
> BCS lets you install & manage custom integrations from **GitHub/GitLab/Gitea** and your own sources, with backups, restore, and version pinning.
BCS is a git-based store UI that can currently manage integrations and blueprints from multiple repository providers.
---
## Contents
- Concepts
- Sources (BCS / HACS / Custom)
- Sources
- Supported Content Types
- UI Overview
- Finding Integrations
- Finding Repositories
- Installing
- Selecting Versions / Downgrading
- Selecting Versions
- Updating
- Uninstalling
- Backups & Restore
- Pinned Repositories
- Release Notes
- Backups and Restore
- Custom Repositories
- HACS Repositories
- Update Entities in Home Assistant
- Background Caching & Performance
- Restart Required
- Update Entities
- Performance and Caching
- Restart Behavior
- Troubleshooting
- FAQ
@@ -29,189 +32,281 @@ It is written for users and admins who want a complete, practical reference.
## 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 Official**: repositories from the official Bahmcloud index
- **HACS**: optional HACS integration source
- **Custom**: repositories you add manually by URL
### Installed Ref
BCS stores the installed ref separately from any version declared inside the repository itself.
That makes update checks more reliable when a repository uses tags or releases that do not exactly match its internal manifest version.
---
## Sources (BCS / HACS / Custom)
## Supported Content Types
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
### Integrations
You can **filter by source** with the **Source** dropdown (All / BCS Official / HACS / Custom).
- Source layout: `custom_components/<domain>/...`
- Install target: `/config/custom_components/<domain>`
- Supports install, update, downgrade, uninstall, backups, restore, and update entities
- Restart required after install, update, uninstall, or restore
### Blueprints
- Source layout: `blueprints/...`
- Install target: `/config/blueprints/...`
- Supports install and uninstall through the store
- Intended for blueprint repositories without integration-specific folder structures
---
## 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)
Store view:
Repository card:
- Name, description, badges (source, installed/update), category
- Buttons: **Install / Update / Uninstall**
- **Readme** expandable
- **Open** to see details (available versions, metadata)
- Search
- Source filter
- Category filter
- State filter
- Sorting
- HACS source toggle
- Pinned repository filtering and sorting
Repository detail view:
- README rendering
- Release notes for provider releases
- Version selector
- Install / Update / Uninstall actions
- Pin / Unpin action
- Backup restore action for integrations
- Category and install target information
---
## Finding Integrations
## Finding Repositories
1. Use **Search** to filter by keywords.
2. Combine with **Category** and **Source**.
3. Sort to surface desired results.
1. Use **Search** to filter by name, description, or URL.
2. Use **Source** to switch between BCS Official, HACS, and Custom repositories.
3. Use **Category** to focus on a specific content type.
4. Use **Pinned** filtering or sorting to surface repositories you watch often.
Descriptions and latest versions are filled progressively by a background process; opening a repo loads details on demand.
Descriptions, metadata, and latest versions may appear progressively because BCS enriches repository information in the background.
---
## 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)
### Integration Install
**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.
1. Open a repository.
2. Optionally select a version.
3. Click **Install**.
4. Restart Home Assistant when prompted.
Internally, BCS:
- downloads the selected repository archive
- extracts `custom_components/...`
- installs every valid integration found there
- stores the installed ref
- creates backups before overwriting existing integration folders
### Blueprint Install
1. Open a blueprint repository.
2. Optionally select a version.
3. Click **Install**.
Internally, BCS:
- downloads the selected repository archive
- extracts `blueprints/...`
- copies blueprint files into `/config/blueprints/...`
Blueprint installs normally do not require a Home Assistant restart.
---
## Selecting Versions / Downgrading
## Selecting Versions
- 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**.
- Use the version selector in the detail view.
- `Latest` uses the newest provider release or tag BCS can determine.
- You can install an older release or tag when available.
- Release notes are shown when the selected version is a provider release with a body.
---
## 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).
### Integrations
**Tip:** Opening a repository detail view forces an immediate check for the latest version for that repo.
- The **Update** button appears when the latest ref differs from the installed ref.
- Updates are also available through **Settings -> Updates** via native Home Assistant update entities.
- Integration updates create backups before overwriting files.
### Blueprints
- Blueprint repositories can also be reinstalled from another selected version.
- The current blueprint path handling is focused on direct deployment to the blueprints folder.
---
## 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.
### Integrations
- Removes the installed integration directories from `/config/custom_components`
- Clears the installed state in BCS
- Usually requires a restart
### Blueprints
- Removes the installed blueprint files recorded by BCS
- Cleans up empty directories below `/config/blueprints` when possible
---
## Backups & Restore
## Pinned Repositories
Before an update/install over existing files, BCS creates a backup:
You can pin repositories to keep important items easy to find.
```
/config/.bcs_backups/<domain>/<timestamp>/
```
Current behavior:
**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.
- Pin or unpin from the detail view
- Filter the store by pinned repositories
- Sort the store with pinned repositories first
- Pinned repositories show a dedicated badge in the store overview
- Pinned state is persisted in settings
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.
---
## Release Notes
When a provider release has a release body, BCS can show release notes in the detail view for the selected version.
Notes:
- Release notes are available for real releases, not every tag or branch
- If no provider release body exists, BCS shows a clear not-available state
---
## Backups and Restore
Integration installs and updates create backups before overwriting existing files.
Backup path:
`/config/.bcs_backups/<domain>/<timestamp>/`
Restore flow:
1. Open the repository detail
2. Click **Restore**
3. Select a backup
4. Confirm restore
5. Restart Home Assistant if prompted
Restore is currently intended for integrations.
---
## 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)
You can add any public repository URL that matches a supported provider style and contains supported content.
**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
BCS attempts to detect:
**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/*```))
- provider
- default branch
- latest version
- metadata from `bcs.yaml`, `hacs.yaml`, or `hacs.json`
- README content
Custom repos get the **Custom** badge and can be filtered via **Source**.
Custom repositories get a **Custom** badge and can be filtered separately.
---
## HACS Repositories
Enable the **HACS official** toggle to include official HACS integrations.
Enable the HACS toggle to include official HACS integration repositories.
- 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).
Current scope:
With many HACS repos, metadata loads in the background; names/descriptions appear progressively and are cached.
- HACS source support is currently focused on integrations
- HACS metadata is used to improve naming and descriptions
---
## Update Entities in Home Assistant
## Update Entities
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)
BCS exposes Home Assistant update entities for installed integrations.
- Found under **Settings -> Updates**
- Shows installed ref and latest ref
- Lets Home Assistant trigger the BCS update pipeline
Blueprint repositories do not currently use the integration-style update entity flow.
---
## Background Caching & Performance
## Performance and Caching
- **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
BCS is designed to keep startup responsive.
- Heavy work runs after Home Assistant startup
- Repo data is enriched in the background
- Repository details are cached
- Version lists are cached
- HACS metadata is cached
Opening a repository detail view can force immediate enrichment for that repository.
---
## Restart Required
## Restart Behavior
After install, update, or restore, BCS raises a **Restart required** item in Home Assistant (Repairs). You can restart directly from there.
Restart usually matters only for integration changes.
- Integration install/update/uninstall/restore: restart expected
- Blueprint install/uninstall: restart usually not needed
BCS uses a Home Assistant repair flow to surface restart requirements for integration changes.
---
## 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.
- **Latest version missing**: open the repository detail once to force a recheck
- **Release notes missing**: the selected version may be a tag or branch without a provider release body
- **Blueprint install fails**: verify the repository really contains a `blueprints/` folder
- **Integration install fails**: verify the repository contains `custom_components/<domain>/manifest.json`
- **Repo appears but cannot install**: metadata can describe the category, but the repository layout still has to match that category
---
## 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.
### Where are integrations installed?
`/config/custom_components/<domain>`
### Where are blueprints installed?
`/config/blueprints/...`
### Are pinned repositories persistent?
Yes.
### Do blueprints require a restart?
Usually no.
### Do integrations require a restart?
Yes, normally after install, update, uninstall, or restore.