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

# Standalone upgrade (GUI)

> Step-by-step guide to upgrading a single (non-clustered) Kvelden Enclave appliance to a new release from the admin GUI. Signed and verified, with a brief reboot and automatic rollback if the new version is unhealthy.

<Info>
  This page covers a **single, non-clustered** appliance. If you run **two or
  more clustered appliances**, use the
  [Cluster in-place upgrade](/deployment/appliance/upgrade/cluster) instead —
  that path has **zero downtime**. A standalone upgrade involves a **brief
  reboot** (a few minutes) while the appliance restarts into the new version.
</Info>

<Note>
  New to how this works? Read [System upgrade](/deployment/appliance/upgrade/overview)
  first — it explains the signed bundle, the A/B slots, and the automatic
  safety net.
</Note>

## Before you start

<AccordionGroup>
  <Accordion title="Sign in as the owner">
    Go to `https://<your-appliance-address>` and sign in with the **owner**
    account. Software updates are owner-only.
  </Accordion>

  <Accordion title="Have the signed bundle ready">
    Obtain `enclave-update-<version>.tar.gz` from your Kvelden account team and
    keep it on the computer you're using. No internet access is needed on the
    appliance.
  </Accordion>

  <Accordion title="Plan a short maintenance window">
    The appliance **reboots once** to activate the new version, so users are
    briefly offline (typically a few minutes). Schedule accordingly and let
    users know.
  </Accordion>

  <Accordion title="Take a backup (recommended)">
    The upgrade takes an automatic safety snapshot, but a fresh verified backup
    (**Admin → Backup & Restore**) beforehand is best practice.
  </Accordion>
</AccordionGroup>

## Upgrade steps

<Steps>
  <Step title="Open Software Update">
    In the admin area, go to **System → Software Update**. You'll see an
    **Upload a bundle** panel and an **Update history** list of previous
    upgrades.
  </Step>

  <Step title="Upload the bundle">
    Select **Choose bundle…** and pick your `enclave-update-<version>.tar.gz`
    file. The upload progress is shown. The appliance accepts only a properly
    named, Kvelden-signed bundle.
  </Step>

  <Step title="Review the preflight report">
    The appliance automatically **verifies and preflights** the bundle:

    * Signature and format are valid.
    * The target version is **newer** than what's installed (downgrades are
      refused).
    * There is enough free disk space to apply.

    Confirm the report shows the expected **from → to** versions and that all
    checks pass. If preflight fails, see [Troubleshooting](#troubleshooting) —
    nothing has been changed on the appliance yet.
  </Step>

  <Step title="Apply the update">
    Select **Apply update** and confirm your password when prompted (step-up
    authentication). This starts the upgrade — from here it runs on its own.
  </Step>

  <Step title="Watch the live progress">
    A progress stepper shows each stage and **follows the upgrade through the
    reboot**:

    1. **Upload bundle** — staged on the appliance.
    2. **Verify & preflight checks** — signature + version + capacity.
    3. **Install to standby slot** — the new OS is written to the inactive A/B slot.
    4. **Reboot & activate** — the appliance restarts into the new slot and
       applies the new application.
    5. **Complete** — the new version is health-checked and committed.

    The appliance is briefly unreachable during **Reboot & activate**. The
    stepper **persists across the reboot** — if you refresh or reopen the page,
    it resumes reporting where the upgrade actually is, and ends with an explicit
    **"completed"** (or a rolled-back **"failed"**).
  </Step>

  <Step title="Verify the new version">
    When the stepper reports **completed**, sign in again and confirm:

    * The version shown under **System** matches the new release.
    * Your data is intact — open a room / file you know.
    * **System → Diagnostics** is green.
  </Step>
</Steps>

## If something goes wrong

The upgrade is **self-healing**. After the reboot the appliance health-checks the
new version:

* **Healthy** → the new version is committed and the previous slot is kept as the
  fallback for the next upgrade.
* **Unhealthy** → the appliance **automatically rolls back** to the previous slot
  and restores the pre-update database snapshot. It comes back on the **old**
  version with your data intact, and the stepper reports **failed** with the
  reason.

You do not need to do anything to trigger rollback — it is automatic and the OS
and application always move together (never a split state).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Preflight failed — bundle rejected">
    The bundle's signature or format didn't validate, or it isn't newer than the
    installed version. Re-download the bundle from Kvelden and confirm it's the
    correct release. Nothing was changed on the appliance.
  </Accordion>

  <Accordion title="Preflight failed — insufficient disk space">
    Free some space and re-run preflight. The most common cause is old uploaded
    bundles: remove previous bundles listed under **Software Update**, then try
    again.
  </Accordion>

  <Accordion title="The page looks stuck during the reboot">
    A brief unreachable window during **Reboot & activate** is normal. Leave
    the page open — it resumes automatically when the appliance is back. If it
    hasn't returned after several minutes, refresh the page; the stepper
    re-attaches to the live status.
  </Accordion>

  <Accordion title="It came back on the old version">
    That's the automatic rollback: the new version failed its health gate, so the
    appliance reverted safely. Review the failure reason in the stepper /
    **Update history**, capture a **support bundle** (**System → Diagnostics**),
    and contact Kvelden support before retrying.
  </Accordion>
</AccordionGroup>

<Card title="Review past upgrades" icon="clock-rotate-left">
  Every upgrade (and rollback) is recorded under **System → Software Update →
  Update history** with the from/to versions, timestamp, and outcome.
</Card>