Project Atlas AetherDev project hub
Atlas project production

openhab-git-sync

Automated two-way Git synchronisation for openHAB deployments that keeps /etc/openhab and selected /var/lib/openhab subtrees version-controlled without relocating live data. A dedicated shadow workspace plus a hardened systemd service ensures configs stay in sync across servers while guarding against jsondb race conditions. On each run, sync live openHAB paths into a shadow workspace, commit local changes, pull remote updates, and apply changes back to the live directories. Detect jsondb updates and restart openHAB when required to avoid race conditions.

Type
System
Lifecycle
Active
Last touched
2025-10-12
Visibility
Public

Purpose

Automated two-way Git synchronisation for openHAB deployments that keeps /etc/openhab and selected /var/lib/openhab subtrees version-controlled without relocating live data. A dedicated shadow workspace plus a hardened systemd service ensures configs stay in sync across servers while guarding against jsondb race conditions.

Current state

All notable changes to this project are documented here following Keep a Changelog conventions. Versions adhere to the YYYY.MM.DD tagging format with optional letter suffixes. Last touched: 2025-10-12. Functionality and completeness: Sync workflow, install, and operations are documented; tests are pending.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • /etc/default/openhab-git-sync config, git remote, bind-mount paths
  • Configuration files (TOML/YAML/JSON/INI/CONF)
Outputs
  • Git commits/pushes, updated openHAB config directories, service restarts as needed

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Contributes in this stage.

Automation Engines

Contributes in this stage.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Artifacts

  • Config keys for workspace, branch, tracked dirs, and permission normalization

Operational notes

Constraints and scars

  • Requires careful bind-mount selection; jsondb updates can require an openHAB restart.

Reliability posture

Failure modes and safe behavior: Config test failures or git errors stop the sync and preserve existing state. Idempotency / retries / batching behavior: Repeated runs converge to Git state; no explicit retries beyond git defaults.

Observability

  • Logs: Service logs available via systemd journal.
  • Metrics/health checks: None built-in; rely on journald and log file
  • Logs: stdout/journald plus /var/log/openhab-git-sync.log with logrotate.

Security and privacy

Store Git credentials in SSH deploy keys or secure credential helpers. Exclude binding directories that include secrets or API keys from Git sync.

Dependencies

Upstream
  • Git remote, systemd, openHAB service

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

openhab-git-sync

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Entry points: usr/local/sbin/openhab-git-sync, systemd unit and timer

  • Top-level folders: docs, etc, scripts, usr

  • Key abstractions: Shadow workspace, bind-mount orchestration, git sync loop, jsondb safety checks

Setup / Build / Run

  • Build system(s): Make; install via scripts/install.sh or make install.
  • Configure /etc/default/openhab-git-sync, then enable openhab-git-sync.timer.