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

7.5 KiB
Raw Blame History

Bahmcloud Store - Full User Guide

This guide explains the current feature set of Bahmcloud Store (BCS) for Home Assistant.

BCS is a git-based store UI that can currently manage integrations and blueprints from multiple repository providers.

Contents

  • Concepts
  • Sources
  • Supported Content Types
  • UI Overview
  • Finding Repositories
  • Installing
  • Selecting Versions
  • Updating
  • Uninstalling
  • Pinned Repositories
  • Release Notes
  • Backups and Restore
  • Custom Repositories
  • HACS Repositories
  • Update Entities
  • Performance and Caching
  • Restart Behavior
  • Troubleshooting
  • FAQ

Concepts

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.

Supported Content Types

Integrations

  • 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

Store view:

  • 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 Repositories

  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, metadata, and latest versions may appear progressively because BCS enriches repository information in the background.

Installing

Integration Install

  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

  • 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

Integrations

  • 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

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

Pinned Repositories

You can pin repositories to keep important items easy to find.

Current behavior:

  • 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

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 URL that matches a supported provider style and contains supported content.

BCS attempts to detect:

  • provider
  • default branch
  • latest version
  • metadata from bcs.yaml, hacs.yaml, or hacs.json
  • README content

Custom repositories get a Custom badge and can be filtered separately.

HACS Repositories

Enable the HACS toggle to include official HACS integration repositories.

Current scope:

  • HACS source support is currently focused on integrations
  • HACS metadata is used to improve naming and descriptions

Update Entities

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.

Performance and Caching

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 Behavior

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

  • 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

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.

Reference in New Issue View Git Blame Copy Permalink