Skip to content

Hibernation

Hibernation is BCDock's lever for "I'm not using this env right now but I want it back later." It collapses an environment from a running container into a gzipped blob, frees the pool slot, drops billing to a flat stored rate, and lets the customer resume on demand — possibly on a different pool in a different region.

The architectural decisions live in ADR-013 (dual-rate billing) and ADR-012 (cross-major-version resume). This page is the public summary.

The two states

State What it is Active billing? Stored billing?
running Container is up, URL responds, BC database mounted yes no
hibernated Container is gzipped to blob storage; pool slot freed no yes (~A$25/month flat)

Reaching hibernated: customer calls bcdock env hibernate <name> (or the portal button). A few minutes later, the env's running container is snapshot-and-uploaded to the region's blob storage, and the pool's container is destroyed. The env-record row stays; the URL becomes inert.

Reaching running again: customer calls bcdock env resume <name>. The platform picks any compatible pool (same BC version × country × artifact-type), copies the blob if needed, and starts a fresh container restored from the snapshot.

What gets snapshotted

The container's complete state, including:

  • BC database — the customer's tables, customizations, custom apps, every change since the env was created
  • Container filesystem — published .app files, certificates the customer dropped in, anything in /BC data dirs
  • Container configuration — environment variables, mounted volumes, the BC server config
  • Container metadata — admin password, Web Service Access Key, BC version, locale

What's not in the snapshot:

  • Pool-level state — Traefik routes, pool agent state, etc. These are reconstructed when the env is allocated to a pool.
  • DNS records — recreated on resume.
  • Per-env Key Vault entries — the admin password lives in the regional Key Vault, not in the snapshot blob.

Where the blob lives

Per region. An env hibernated in australiaeast writes its blob to the australiaeast storage account. Cross-region resume copies the blob to the target region's storage account first, then restores from there.

Soft-delete is enabled on the storage account (7-day recovery). After env delete + 7 days, the blob is unrecoverable.

Cross-version resume

If a customer's env was hibernated at BC v27 but the only available pool in the requested region is at v28, the platform requires explicit confirmation before proceeding:

bcdock env resume my-env
# error: cross-version resume requires confirmation
# error: env hibernated at 27.0; available pool is at 28.0
# error: re-run with --version 28 to confirm

bcdock env resume my-env --version 28 --wait
# proceeds with the cross-major upgrade

The platform doesn't make this call silently — version upgrades can break extensions and shift data shape. The customer (or their agent) has to confirm.

Cross-major-version backwards resume is not supported. Forwards is the documented escape hatch when an old BC major is being drained.

The mechanism is decomposed (since 2026-04) into "create empty container at the target version" and "restore the snapshot blob into the running container" — two separate steps so the upgrade and the restore each fail in clean ways.

The dual-rate billing model

Active and stored states bill at independent rates. Per environment, billed per second:

  • Active rate — the per-second equivalent of the customer's plan tier (Starter A$259/month if continuous, Professional A$389/month, etc.) or the PAYG hourly rate (A$0.59/hour)
  • Stored rate — A$25/month flat, regardless of plan tier

Why flat: the underlying cost is ~A$0.30/month for a 10 GB BC backup blob, which is the same on every plan. Tiering it would just be price discrimination.

The math customers care about: if you run an env active for half the month and hibernated for the other half, your bill prorates to roughly half the active cap plus half the stored rate — not "half a month of active billing" alone.

Why hibernation is first-class

Two design principles, both visible in the rest of the system:

  1. Most environments aren't running most of the time. A consultant testing a customisation uses the env for 4 hours, then hibernates for two weeks until the next client meeting. A CI pipeline spins one up per PR, runs tests, hibernates between pushes. The whole stack — billing, blob storage, autoscaler — is built for this shape.
  2. The flat stored rate makes "spin up an env per PR" affordable. Without it, leaving 5 PRs open over a weekend would cost ~A$1500. With it, ~A$5. That's the difference between "BCDock is a vendor we use sparingly" and "BCDock is the primitive in our pipeline."

Performance

Operation Typical time Notes
Hibernate ~1–3 minutes Container gzipped to blob, then container destroyed. Most time is in the gzip + upload.
Resume (warm pool, same region, same version) ~1–2 minutes Container started, blob downloaded, restore completes. Most time is in the download.
Resume (cross-region) ~5–15 minutes Adds blob copy from source region storage to target region storage.
Resume (cross-major version) ~5–15 minutes Adds the BC platform upgrade.

The autoscaler's pool warming targets the warm-pool case — most resumes finish in 1–2 minutes against a pool that already has the right combination running.

What's planned (not shipped)

  • Templates (H2 2026) — hibernated env with identity detached, instantiate new envs from a saved baseline at the flat stored rate. Same blob mechanics; identity rewrite at clone time.
  • Cloning (H2 2026) — copy an env's state into a new env with a fresh identity. Built on the hibernation primitive.
  • Auto-hibernate on idle — a heuristic-driven policy ("env hasn't been hit in N hours, hibernate it"). Listed but contentious; waiting for customer signal.

Read more