Skip to content

How backups work

ConstellaWP does not store backup files. You connect a bucket you already own; the control plane only orchestrates the job, tracks metadata, and applies retention. Archives never transit through ConstellaWP servers.

That model is BYOS — Bring Your Own Storage.

ConstellaWP speaks S3-compatible APIs:

Use a named provider when it matches the form. Use S3-compatible when you have a custom API endpoint.

The agent:

  1. Collects system info and writes a manifest (WordPress/PHP versions, plugins, themes, size)
  2. Dumps the database
  3. Archives the whole WordPress installation

Everything lands in a single zip, split into two top-level directories:

backup-20260813-181052.zip
├── files/ Everything WordPress: core, wp-config.php, wp-content
└── database/
└── database.sql The full dump

The dump and the site files live in separate directories on purpose. A file sitting at the root of your site can never take the dump’s place in the archive, whatever it is named.

To extract a backup by hand, copy the contents of files/ over your WordPress directory, then import database/database.sql into the database your wp-config.php points to. The dump drops each table before recreating it, so it replaces what is already there.

Object key pattern:

{path prefix}/{site id}/backup-{YYYYMMDD-HHMMSS}.zip

The default path prefix is backups. Changing the prefix later only affects new backups.

  1. You click backup, a policy fires on schedule, or an update runs with backup first.
  2. ConstellaWP creates a backup job and presigns a PUT URL on your destination (valid for 2 hours).
  3. The worker tells the agent to start. The agent builds the archive on the WordPress server.
  4. The agent uploads directly to your bucket using that URL.
  5. The agent reports completion. ConstellaWP stores path, size, manifest, and expires_at from the retention of the frequency that took it, or the policy’s retention for a manual or pre-update backup.

Upload URLs are short-lived on purpose. Download URLs used in the UI expire in 15 minutes; restore uses a longer window so the agent can finish a safety backup first.

Priority:

  1. WP-CLI when available (wp db export, then archive)
  2. Fallback PHP (shell_exec / WP_Filesystem)

Large sites may need enough disk for a temporary archive. The agent reports free disk in capabilities.

  • Manual: site Backups page (owners and admins). Requires at least one destination on the organization.
  • Scheduled: a backup policy (daily / weekly / monthly at 02:00 server time).

If the site has no policy, a manual backup uses the organization’s first destination.

On Storage, Test connection writes then deletes a small probe object ({prefix}/constellawp-connection-test-….txt). That checks write and delete, not only listing. Fix IAM/key permissions if the test fails — backups will fail the same way.

  • It does not keep a second copy of the zip
  • Deleting a destination in ConstellaWP does not delete objects already in the bucket
  • Hosting-provider backups (cPanel lists, Cloudways snapshots) are separate; see Hosting