Home Assistant Version Control

For Docker users who aren't using the Home Assistant app, you have three deployment options:

Option A: Docker Compose (recommended):

1. Download the compose.yaml file:

   curl -o compose.yaml https://github.com/saihgupr/HomeAssistantVersionControl/raw/develop/compose.yaml
   

2. Edit the file to set your paths and timezone:

   nano compose.yaml
   # Update the volume path: /path/to/your/ha/config
   # Update timezone: TZ environment variable (e.g., America/New_York)
   

3. Start the service:

   docker compose up -d
   

Access the interface at http://localhost:54001.

Option B: Docker Run (pre-built image):

docker run -d \
  -p 54001:54001 \
  -v /path/to/your/config:/config \
  -e TZ=America/New_York \
  -e SUPERVISOR_TOKEN=your_long_lived_access_token_here \
  -e HA_URL=http://homeassistant.local:8123 \
  --name home-assistant-version-control \
  ghcr.io/saihgupr/home-assistant-version-control:latest

Replace /path/to/your/config with the actual path to your Home Assistant configuration directory.

Option C: Build locally:

git clone https://github.com/saihgupr/HomeAssistantVersionControl.git
cd HomeAssistantVersionControl/homeassistant-version-control
docker build --build-arg BUILD_FROM=alpine:latest -t home-assistant-version-control .

docker run -d \
  -p 54001:54001 \
  -v /path/to/your/config:/config \
  -e TZ=America/New_York \
  -e SUPERVISOR_TOKEN=your_long_lived_access_token_here \
  -e HA_URL=http://homeassistant.local:8123 \
  --name home-assistant-version-control \
  home-assistant-version-control

Access the interface at http://localhost:54001.

You can use the additional_paths feature to version control configurations stored on remote shares (like a NAS or another server). This is perfect for tracking Frigate configurations or other Docker-based apps running elsewhere.

Step 1: Set up Network Storage in Home Assistant

1. Navigate to Settings → System → Storage.
2. Click "Add network storage".
3. Give it a name (e.g., frigate).
4. Set Usage to Share or Media.
5. Enter your server details and mount point.

Step 2: Add to Version Control Once mounted, the share will be available at /share/frigate (if usage was set to Share) or /media/frigate (if set to Media). Add this path to your additional_paths in the app configuration:

additional_paths:
  - /share/frigate

Benefits:

• Frigate Configuration Recovery: If a complex config change breaks your detection, you can instantly see the side-by-side diff and roll back your config.yml to a known working state, even if Frigate is running on a completely separate machine or VM.

The application can be configured through the web UI Settings page or via environment variables for containerized deployments.

Available Settings

Environment Variable Configuration

For containerized deployments (especially when not persisting the /data directory), you can configure runtime settings using environment variables. This is particularly useful for:

• Docker/Podman deployments without persistent data volumes
• Infrastructure-as-code configurations
• Automated deployments with predefined settings

Precedence order (per-setting):

1. Settings file (/data/runtime-settings.json) - highest priority
2. Environment variables - middle priority
3. Default values - fallback

Environment Variable Reference

Notes:

• Boolean values are case-insensitive and accept: true/false, yes/no, 1/0
• String values (units, types) are case-insensitive: SECONDS and seconds are equivalent
• Invalid values trigger warnings in logs and fall back to defaults
• Empty values are ignored

Docker Examples

Docker Compose with environment variables:

version: '3.8'
services:
  havc:
    image: ghcr.io/saihgupr/home-assistant-version-control:latest
    ports:
      - "54001:54001"
    volumes:
      - /path/to/your/config:/config
    environment:
      - TZ=America/New_York
      - DEBOUNCE_TIME=10
      - DEBOUNCE_TIME_UNIT=minutes
      - HISTORY_RETENTION=true
      - RETENTION_TYPE=time
      - RETENTION_VALUE=30
      - RETENTION_UNIT=days

Docker Run with environment variables:

docker run -d \
  -p 54001:54001 \
  -v /path/to/your/config:/config \
  -e TZ=America/New_York \
  -e DEBOUNCE_TIME=10 \
  -e DEBOUNCE_TIME_UNIT=minutes \
  -e HISTORY_RETENTION=true \
  -e RETENTION_TYPE=time \
  -e RETENTION_VALUE=30 \
  -e RETENTION_UNIT=days \
  --name home-assistant-version-control \
  ghcr.io/saihgupr/home-assistant-version-control:latest

Validation and Logging:

When the container starts, you'll see detailed logging showing where each setting value came from:

[init] Runtime settings loaded:
[init]   debounceTime: 10 (env: DEBOUNCE_TIME)
[init]   debounceTimeUnit: 'minutes' (env: DEBOUNCE_TIME_UNIT)
[init]   historyRetention: true (env: HISTORY_RETENTION)
[init]   retentionType: 'time' (default)
[init]   retentionValue: 30 (env: RETENTION_VALUE)
[init]   retentionUnit: 'days' (default)

Invalid values will trigger warnings:

[init] Warning: Invalid DEBOUNCE_TIME='abc', Expected integer, got: 'abc'. Using default: 5

The Workflow

1. File Watcher: The system continuously monitors your /config folder for changes to YAML files.
2. Stabilization: When a change is detected, it waits 2 seconds to ensure Home Assistant has finished writing the file (preventing corruption).
3. Debounce: It then waits for your configured Debounce Time (default 5s) to batch related edits into a single commit.
4. Snapshot: A Git commit is created with a timestamp.
5. Cleanup: If enabled, old snapshots are consolidated periodically.

What is Tracked?

The app automatically tracks configuration files while ignoring system files.

Automatic Branch Detection

The app is branch-agnostic and will automatically detect the active branch of your repository.

• New Installations: Automatically default to main.
• Existing Repositories: If your repository already uses master (or any other branch), the app will detect it and continue to use it without intervention.
• Manual Branch Swapping: If you manually rename your branch (e.g., git branch -m master main), the app will automatically update its sync logic to match the new branch name.

You can automatically sync your configuration to a private remote repository. This is highly recommended for off-site backups.

Custom Repository Setup (Gitea/Self-Hosted)

If you are using a custom Git server like Gitea, follow these steps to ensure a smooth sync (note: this is not required for standard GitHub setups):

1. Create a Private Repository: Log in to your Git server and manually create a private repository named VersionControlBackup before attempting to sync from the UI.
2. Authentication URL: Use the following URL format in the Cloud Sync settings, substituting your token, IP/domain, and username:

   http://YOUR_API_TOKEN@YOUR_SERVER_IP:PORT/YOUR_USERNAME/VersionControlBackup.git
   

API for advanced users or automation.

Endpoint Details

POST /api/git/hard-reset

Reset the repository to a specific commit. WARNING: This is destructive and will discard all changes since that commit.

Parameters:

• commitHash (string, required): The full or short hash of the commit to reset to.
• createBackup (boolean, optional): If true, creates a safety backup commit of the current state before resetting. Default: false.

Example:

{
  "commitHash": "a1b2c3d4",
  "createBackup": true
}

POST /api/restore-commit

Restore all files to their state at a specific commit. This creates a new commit on top of the current history, preserving history.

Parameters:

• commitHash (string, required): The hash of the commit to restore.

Example:

{
  "commitHash": "e5f6g7h8"
}

POST /api/restore-file

Restore a single file to its state at a specific commit.

Parameters:

• commitHash (string, required): The hash of the commit containing the version of the file you want.
• filePath (string, required): The relative path to the file (e.g., automations.yaml).

Example:

{
  "commitHash": "i9j0k1l2",
  "filePath": "scripts.yaml"
}

POST /api/retention/cleanup

Run the history retention cleanup process with custom parameters.

Parameters:

• days (number, optional): Keep history for the last N days.
• hours (number, optional): Keep history for the last N hours.
• minutes (number, optional): Keep history for the last N minutes.
• months (number, optional): Keep history for the last N months.

Example:

curl -X POST http://homeassistant.local:54001/api/retention/cleanup \
  -H "Content-Type: application/json" \
  -d '{"hours": 24}'