cw4g/timemachine-dashboard

By cw4g

•Updated 8 months ago

Image

1.2K

Overview Tags

cw4g/timemachine-dashboard repository overview

⁠Time Machine Dashboard

A lightweight web dashboard for monitoring macOS Time Machine backups stored on a network share (NAS).

⁠Features

Monitor multiple Time Machine backup machines
View snapshot history grouped by date
Health check endpoint for monitoring tools (e.g., Uptime Kuma)
JSON API for integration with other tools
Lightweight Docker image based on Python slim

⁠Quick Start

docker run -d \
  --name timemachine-dashboard \
  -p 5000:5000 \
  -v /path/to/timemachine:/data:ro \
  cw4g/timemachine-dashboard

⁠Docker Compose

services:
  timemachine-dashboard:
    image: cw4g/timemachine-dashboard
    container_name: timemachine-dashboard
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - /path/to/timemachine:/data:ro
    environment:
      - TIMEMACHINE_PATH=/data

⁠Environment Variables

Variable	Default	Description
`TIMEMACHINE_PATH`	`/data`	Path to the Time Machine backup directory inside the container
`DEBUG`	`false`	Enable Flask debug mode

⁠Endpoints

Endpoint	Description
`/`	Web dashboard
`/api/backups`	JSON API with all backup data
`/api/homepage`	Simplified API for Homepage⁠ integration
`/health`	Simple health check (always returns 200)
`/health/backup?max_hours=N`	Returns 503 if any backup is older than N hours (default: 24)

⁠Health Monitoring

The /health/backup endpoint is designed for use with monitoring tools like Uptime Kuma:

URL: http://your-server:5000/health/backup?max_hours=48
Expected status: 200

Returns HTTP 503 if any backup exceeds the specified age threshold.

⁠Homepage Integration

The /api/homepage endpoint provides data for Homepage⁠ Custom API widgets.

⁠Query Parameters

Parameter	Default	Description
`ok_days`	2	Maximum age in days for OK status
`warning_days`	7	Maximum age in days for Warning status (Error if exceeded)

Examples:

/api/homepage                         # Default: OK < 2 days, Warning 2-7 days
/api/homepage?ok_days=1&warning_days=3  # Stricter: OK < 1 day, Warning 1-3 days
/api/homepage?ok_days=7&warning_days=14 # Relaxed: OK < 7 days, Warning 7-14 days

⁠Example Response

{
  "total_machines": 3,
  "ok_count": 2,
  "warning_count": 1,
  "error_count": 0,
  "status": "warning",
  "oldest_backup_days": 3.0
}

⁠Option 1: Docker Labels (Auto-Discovery)

services:
  timemachine-dashboard:
    image: cw4g/timemachine-dashboard
    labels:
      - homepage.group=Infrastructure
      - homepage.name=Time Machine
      - homepage.icon=mdi-backup-restore
      - homepage.href=https://tm.example.com
      - homepage.description=Backup Status
      - homepage.widget.type=customapi
      - homepage.widget.url=http://timemachine-dashboard:5000/api/homepage
      - homepage.widget.mappings[0].field=total_machines
      - homepage.widget.mappings[0].label=Machines
      - homepage.widget.mappings[0].format=number
      - homepage.widget.mappings[1].field=ok_count
      - homepage.widget.mappings[1].label=OK
      - homepage.widget.mappings[1].format=number
      - homepage.widget.mappings[2].field=warning_count
      - homepage.widget.mappings[2].label=Warning
      - homepage.widget.mappings[2].format=number
      - homepage.widget.mappings[3].field=error_count
      - homepage.widget.mappings[3].label=Errors
      - homepage.widget.mappings[3].format=number

With custom thresholds:

      - homepage.widget.url=http://timemachine-dashboard:5000/api/homepage?ok_days=1&warning_days=3

⁠Option 2: services.yaml

- Time Machine:
    icon: mdi-backup-restore
    href: https://tm.example.com
    widget:
      type: customapi
      url: https://tm.example.com/api/homepage
      mappings:
        - field: total_machines
          label: Machines
          format: number
        - field: ok_count
          label: OK
          format: number
        - field: warning_count
          label: Warning
          format: number
        - field: error_count
          label: Errors
          format: number

⁠How It Works

The dashboard scans the mounted directory for .sparsebundle directories (Time Machine backup format) and reads the plist files inside:

com.apple.TimeMachine.SnapshotHistory.plist - Backup snapshot list
com.apple.TimeMachine.MachineID.plist - Machine UUID

⁠Requirements

Your Time Machine backups must be stored as .sparsebundle disk images on a network share. This is the default format when using Time Machine with a NAS.

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:fcb9f16c7…

Size

17.9 MB

Last updated

8 months ago

docker pull cw4g/timemachine-dashboard