> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Ghost safely

> Use StackShift’s curated upgrade graph, mandatory pre-upgrade recovery point, digest-pinned runtime update, and automatic rollback path.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Move a publication to a tested Ghost release without accepting arbitrary tags or performing an unattended upgrade.

## Prerequisites

* A running native Ghost installation
* A target release whose `upgrade_predecessors` includes the current version
* Working database and stack backup/restore infrastructure

## Workflow

<Steps>
  <Step>
    Review the current version and the upgrade offered in the Ghost overview.
  </Step>

  <Step>
    Read the target Ghost release notes and check integrations or themes outside StackShift.
  </Step>

  <Step>
    Choose Upgrade and confirm the recovery-point warning.
  </Step>

  <Step>
    Wait for the pre-upgrade backup and digest-pinned deployment to complete.
  </Step>

  <Step>
    Validate the site, admin, theme, members, integrations, and mail after upgrade.
  </Step>
</Steps>

## Only tested paths are accepted

StackShift does not accept an arbitrary Ghost tag or a target version that merely looks newer. The target catalog entry must explicitly list the installed version as a supported predecessor. The dashboard displays an upgrade action only when such a target exists.

## Upgrade sequence

The operation is always explicit and user-approved. StackShift does not schedule unattended Ghost upgrades.

```text Safe upgrade operation theme={null}
1. Create recovery record with reason pre_upgrade
2. Stop Ghost and capture MySQL + content + current release
3. Validate the current-to-target catalog edge again
4. Replace only the Ghost web image and exact digest
5. Deploy the updated native stack
6. Record the target version, image, and digest
```

## Automatic rollback

If updating or deploying the new runtime fails, StackShift restores the pre-upgrade MySQL backup and the prior stack backup. The failure remains visible and reports that the prior release was restored.

* Rollback requires both backup artifact IDs.
* Database restore runs before runtime/content restore.
* A rollback failure is reported separately because it requires operator attention.
* After any rollback, manually validate the publication before resuming writes.

## Before approving an upgrade

* Review Ghost’s upstream breaking changes.
* Check whether a custom theme declares compatibility with the target major.
* Confirm backup storage and recent recovery operations are healthy.
* Create a private staging clone and test the same upgrade there first for important sites.
* Schedule a maintenance window because coordinated backup pauses Ghost writes briefly.

## Expected result

<Check>
  Ghost runs the exact catalog image and digest for the target version, with a completed pre-upgrade recovery point retained for recovery.
</Check>

## Common failures

<Warning>
  * The target release is not in the StackShift catalog.
  * The current version is not an approved predecessor.
  * The pre-upgrade recovery point cannot complete.
  * The new image cannot be pulled or fails digest validation.
  * The runtime update fails and rollback also encounters unavailable backup infrastructure.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Create a private Ghost staging clone" href="/ghost/private-staging-clones">
    Clone production Ghost data into a separate native project with a new database, new runtime credentials, generated domain, authenticated ingress, and outbound mail disabled.
  </Card>

  <Card title="Ghost recovery points and restore" href="/ghost/recovery-points-and-restore">
    Capture Ghost’s MySQL data, persistent content, and exact runtime release as one coordinated recovery point, then restore the complete set through a durable operation.
  </Card>

  <Card title="Ghost troubleshooting and limitations" href="/ghost/troubleshooting-and-limitations">
    Diagnose native Ghost provisioning, database, image, routing, mail, recovery, staging, and upgrade failures using persisted operation state and clear resource boundaries.
  </Card>
</CardGroup>