bahmcloud/bahmcloud_store
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity
Files
113c951028068a9a486a01b06197f0e93aa015e0
bahmcloud_store/README_FULL.md
René Bachmann 113c951028 Full
2026-01-19 08:09:48 +00:00

6.7 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.

TL;DR: 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

  • Index (store.yaml): your curated list of repositories. Example: 
    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 View Git Blame Copy Permalink