Technical Docker Restore Verification

Docker restore verification

This reference covers the independently deployed yptDocker tools tools/avideo_backup_restore.php, tools/BackupRestoreMonitor.php and tools/verify_avideo_restore.py, reviewed on 2026-10-29. These deployment scripts are separate from the AVideo Streamer and plugins; inspect the installed files and configuration before changing them. Start with the backup guide for general recovery planning.

Private completion records

The existing CLI writes private receipts under /var/lib/avideo-restore-status/<avideoSiteName>/: directory permissions 0700, receipt permissions 0600. last_attempt.json records the latest attempt, current.json the exclusive lock owner's operation, and last_success_restore.json the last fully completed, checked restore. Backup has a separate last_success_backup.json. Successful operations retain up to 120 dated run receipts. There is no public status endpoint.

success requires the existing commands and post-operation checks to pass. For restore, each copied volume also needs an empty offline rsync -ani --delete comparison. This checks rsync metadata and copy completion; it is not an independent hash of every media byte. Checks also cover restored mount paths, project containers running without OOM, configured healthchecks, database access, nonempty core tables, a meaningful homepage and a nonempty JSON catalog. They do not certify every database row or an authenticated purchase, encoding job or broadcast end to end.

Failed, skipped and incomplete attempts preserve the previous success. A receipt showing starting or running with a missing or mismatched process, or an old last success, needs investigation. Do not remove a lock file solely because the file exists. UTC RESTORE_EVENT entries record stages; RESTORE_RESULT reports success only after the checks pass.

Bounded lock waiting

The reviewed CLI uses /run/lock/avideo-demo-restore.lock for exclusive backup/restore serialization. The monitor's waitForLock() tries an exclusive, nonblocking flock and waits up to 60 seconds on contention, using monotonic time and sleeps of at most 200 ms. A short security audit holding a shared flock can finish before the restore proceeds. The exclusive lock remains held throughout the operation; do not bypass the lock or disable the audit.

While waiting, a receipt remains status: starting with stage: waiting_lock. lock_wait_timeout_seconds records the bound, and lock_wait_seconds records elapsed waiting when acquisition completes or times out. The waiting contender can update its own dated receipt and last_attempt, but cannot replace current before acquiring the exclusive lock. A timeout is skipped_locked, reason lock_busy, exit 75, and preserves the last success. An unavailable lock file is a separate failure. Repeated timeouts still require investigation; waiting is not a guarantee that every scheduled attempt will run.

The Tutorials deployment also has independent security-hardening verification and recovery behavior. Preserve those adaptations, Compose commands, mounts and images. Do not replace the installed CLI with an entire local checkout merely to update its lock handling. The monitor class is backwards compatible: deploy it atomically before updating the caller. No PHP service reload is needed for this CLI source change.

Validation and limits

The verifier's default domain is demo.avideo.com; other deployments must provide their own non-secret AVIDEO_RESTORE_DOMAIN. Read-only service verification confirms present health and must not be presented as a historical restore receipt. Installing a monitor or passing isolated tests does not prove a production restore has subsequently succeeded. Read the receipt from the next normal scheduled operation. Do not trigger a restore solely to produce a green status; the existing operation stops containers and replaces data.

Isolated tests in the yptDocker repository:

php tests/backup-restore-monitor-test.php
python3 tests/backup-restore-lock-test.py

The Linux flock integration test uses temporary files, a Python shared lock and PHP workers. It verifies waiting, bounded timeout, exclusive ownership, serialized contenders, unchanged owner state while waiting, and last-success preservation. It never loads deployment configuration or invokes the backup/restore CLI. Production end-to-end restore validation remains a separate operation.