Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
Goal

Identify which Ghost subsystem failed, take the safest supported action, and know when the requested capability is intentionally outside the first release.

​
Prerequisites

  • Access to the Ghost project overview
  • Permission to view project logs and operations

​
Workflow

1
Read the active operation banner and note its status, step, attempt count, and last error.
2
Check the Ghost installation, managed database, stack, node, and route separately.
3
Correct the underlying capacity, DNS, registry, backup, or provider issue.
4
Use Retry provisioning only for a failed initial installation; use a new explicit operation for backup, staging, restore, or upgrade.
5
Validate the public site and Ghost Admin after recovery.

​
Read the operation first

  • queued: no worker has claimed the operation yet.
  • provisioning_database: inspect the managed MySQL resource and database worker.
  • creating_mail_credential: retry only after control-plane persistence is healthy.
  • creating_native_stack: inspect stack validation and project placement.
  • deploying_native_stack or waiting_reconcile: inspect node reachability, containerd/Kata capability, image pull, digest, health, and Caddy.
  • backing_up_database or backing_up_content: inspect backup storage and the corresponding backup resource.
  • restoring_database or restoring_content_and_release: stop editorial writes and investigate restore infrastructure before retrying.
  • applying_pinned_upgrade: inspect target-image pull and runtime health; then confirm whether automatic rollback completed.

​
Provisioning failures

  • Hosted plan gate: upgrade to Ignite or higher, or use an eligible connected node.
  • Capacity gate: wait for a fresh capability report, free memory, leave drain mode, or select another node.
  • Database timeout: inspect the managed MySQL record; do not create an external database as a workaround.
  • Image pull or digest mismatch: the platform catalog or published artifact must be corrected; do not replace the image with an arbitrary tag.
  • Failed initial provision: after correcting the cause, use Retry provisioning so the idempotent worker reuses already-created resources where possible.

​
Site or admin URL does not load

  • Confirm the installation and managed database both report running.
  • Check that the node agent and Caddy are healthy.
  • For a custom domain, verify DNS before reattaching it.
  • Confirm port 2368 is internal to the Ghost runtime; do not expose a second public port manually.
  • For staging, follow the StackShift authentication redirect and then sign in to Ghost separately for /ghost/.

​
Mail failures

  • Transactional: check that Ghost is running, mail is enabled, and the selected sender domain is verified.
  • Transactional: inspect StackShift Mail events, bounces, suppressions, and reputation.
  • Newsletter: verify Mailgun domain, region, key, and sending authorization.
  • Remember that Mailgun does not handle the native transactional path.
  • Never extract or copy the bridge token; rotate it by using supported restore/lifecycle behavior.

​
Recovery, staging, and upgrade failures

  • A failed recovery point is never restorable; create a new point after fixing backup infrastructure.
  • Ghost should restart after a backup failure, but verify it manually when the operation reports an error.
  • A staging operation continues after its source recovery point completes; poll the staging operation until it returns a target project and URL.
  • If upgrade deployment fails, inspect whether the error says the prior release was restored.
  • If rollback also fails, stop writes and involve an operator before attempting another restore or upgrade.

​
Deletion behavior

Deleting a Ghost project first disables mail and rotates the stored credential, then reconciles removal of the native stack, content volume, managed database, recovery metadata, and routing. Cleanup may continue through retries when a node or database worker is temporarily unavailable.

​
Intentional first-release limitations

  • Fresh installations only; Ghost import and migration are not included.
  • No external databases; native Ghost requires StackShift-managed MySQL 8.
  • No StackShift theme installer or arbitrary-theme lifecycle.
  • No unattended automatic upgrades or arbitrary image tags.
  • No ActivityPub control-plane integration.
  • No Tinybird or other analytics sidecar.
  • A legacy Ghost marketplace template may remain visible until native Ghost reaches general availability; existing template stacks stay editable but are not native Ghost projects.

​
Information to collect for support

  • Project ID and operation ID.
  • Operation type, status, step, attempt count, and last error.
  • Deployment mode and target node ID, without sharing credentials.
  • Managed database status and latest backup status.
  • Whether the issue affects the public URL, /ghost/, transactional mail, newsletters, or only staging.
  • Approximate failure time and any relevant node, stack, or mail event logs.

​
Expected result

You can isolate the failure to control-plane validation, MySQL provisioning, native stack deployment, node runtime, routing, backup/restore, or mail without introducing an unsupported workaround.

​
Common failures

  • Working around native validation by editing the generated stack directly.
  • Assuming a database backup also contains the content volume.
  • Assuming a completed source recovery point means staging has finished.
  • Repeating an upgrade before confirming rollback health.
  • Including database passwords, bridge tokens, Mailgun keys, or owner credentials in support material.

Native Ghost API reference

Automate native Ghost creation, operation polling, actions, domains, recovery, staging, upgrades, and mail through the authenticated StackShift API.

Recovery states, logs, and troubleshooting

Read the operation state on a resource — its status, current step, attempt count, retryable flag, and last error — together with logs, instead of treating a single “error” badge as the whole story.

Stack logs, health, and placement

Use the stack detail, logs, and placement information to understand how the stack is actually running.

Events, webhooks, and timelines

List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.