WPHammer
Log in
  • Scheduled dispatch and per-server throttling
  • Incremental chains
  • Restoring time capsules
  • Configuration
  • Related

    • Time Capsules

    Time capsules are WPHammer's most comprehensive backup type. They capture both the database and all site files, upload everything to S3-compatible storage, support incremental chains to minimize transfer size, and can restore to the original site or an entirely different server. Use time capsules for disaster recovery, long-term archival, and site migration.

    How time capsules work

    Each site can have a TimeCapsuleConfig that controls scheduling and retention. When a capsule is created — either manually via StartCapsuleAction or on schedule — it dispatches the CreateTimeCapsulePipeline with four steps:

    1. Database export

    The ExportDatabaseJob connects via SSH and runs wp db export --single-transaction, pipes the output through gzip, and uploads the compressed dump to S3 at capsules/{server_id}/{site_id}/{timestamp}/database.sql.gz. The db_size_bytes is recorded on the TimeCapsule model.

    2. Manifest collection

    The CollectCapsuleManifestJob generates a SHA256 file manifest of the site, similar to file backups. If a previous capsule's manifest exists, the ManifestDiffService compares them. If less than 80% of files changed, the capsule is marked incremental.

    3. File archive

    The CreateCapsuleArchiveJob builds the file archive:

    • Full archive — a tar.gz of the entire site (excluding caches and backup directories), uploaded as files-full.tar.gz
    • Incremental archive — only changed files, uploaded as files-incremental.tar.gz alongside a deletions.json listing removed files

    Default exclusions match file backups: wp-content/cache, wp-content/upgrade, wp-content/backup-*, wp-content/ai1wm-backups, wp-content/updraft. Additional exclusions can be configured via file_excludes on the config.

    4. Finalization

    The FinalizeCapsuleJob marks the capsule status as Completed and sets completed_at.

    Scheduled dispatch and per-server throttling

    The DispatchScheduledCapsulesCommand runs once per hour and dispatches capsules for active TimeCapsuleConfig records whose effective hour has passed:

    • Configs with Daily frequency run every day
    • Configs with Weekly frequency run on Sundays
    • Capsules are skipped if one has already been created today

    Per-server throttling is enforced during dispatch. The command tracks which servers already have an active capsule deployment (Queued or Running status) and skips additional configs on the same server. This prevents multiple capsule jobs from competing for SSH access and disk I/O on the same machine, ensuring capsules complete reliably even when many sites share a server.

    Like backup configs, when preferred_hour is not set, the effective hour is auto-determined using a CRC32 hash of the site ID across the 0–5 AM UTC window.

    Incremental chains

    Time capsules support incremental chains — a sequence of one full capsule followed by multiple incremental capsules. During restore, the DownloadCapsuleJob walks backward through capsule history to find the most recent full capsule, then collects all incrementals between it and the target capsule. The restore applies them in order: full first, then each incremental, with deletions applied at each step.

    This chain-based approach means daily capsules after the first full one are small and fast, while still allowing restore to any point in the chain.

    Restoring time capsules

    Time capsules support two restoration modes:

    Restore to original site

    The RestoreCapsuleAction dispatches the RestoreTimeCapsulePipeline with five steps:

    1. Pre-restore snapshot — creates a safety snapshot of the current state via PreRestoreSnapshotJob
    2. Download capsule — DownloadCapsuleJob downloads the database dump and file archives (resolving the incremental chain if needed)
    3. Restore database — RestoreCapsuleDatabaseJob imports the database using wp db import
    4. Apply files — ApplyCapsuleFilesJob extracts the full archive first, then applies each incremental archive in sequence, removing deleted files listed in each deletions.json
    5. Cleanup — PostCapsuleCleanupJob removes temporary files, flushes WordPress caches, and fixes permissions

    Restore to a new site

    The RestoreCapsuleToNewSiteAction dispatches the RestoreCapsuleToNewSitePipeline — a seven-step process that creates a brand new site on a different server from a capsule:

    1. Create database and user via SSH
    2. Create the WordPress site on Forge
    3. Create a custom domain on Forge
    4. Set up configuration directories
    5. Download the capsule to the destination server
    6. Restore the database and files to the new site
    7. Clean up and finalize

    This makes time capsules the tool for site migration and disaster recovery across servers.

    Configuration

    The TimeCapsuleConfig controls scheduling and retention:

    Setting Description
    frequency Manual, daily, or weekly scheduling
    preferred_hour UTC hour for scheduled runs, or auto-staggered
    is_active Enable or disable scheduled capsules
    file_excludes Additional paths to exclude from archives
    retention_days Days to keep capsules (default 365)

    Related