bahmcloud/bahmcloud_store
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity
Files
5cf365f354c1bb4162ab02f836f07f0754eeca89
bahmcloud_store/README_FULL.md

7.4 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink