> ## Documentation Index
> Fetch the complete documentation index at: https://fossorial-docs-pangolin-helm-devel-prerelease.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Update

> Keep your self-hosted Pangolin server up to date with the latest features and security patches

Updating Pangolin is straightforward since it's a collection of Docker images. Simply pull the latest images and restart the stack.

This page covers updating your self-hosted Pangolin server. To update sites and clients, see the respective guides:

<CardGroup cols={2}>
  <Card title="Update Sites" icon="plug" href="/manage/sites/update-site">
    Update sites to the latest version.
  </Card>

  <Card title="Update Clients" icon="desktop" href="/manage/clients/update-client">
    Update your installed client to the latest version.
  </Card>
</CardGroup>

## Migration Scripts

When Pangolin starts and detects a version update, it runs migration scripts automatically to update your database and configuration files. Pangolin stores the last successfully run version in the database, so it knows which scripts still need to run. Scripts run in order, starting from the oldest unrun script through the latest.

These are commonly SQL schema updates, and sometimes data migrations.

If a release includes a Badger update, Pangolin also tries to update the Traefik config when it still matches the default Pangolin installer Traefik config. If Pangolin cannot apply that change, it fails silently so you can update Badger yourself.

A failed database migration blocks startup and prevents the server from running.

If you are using SQLite, Pangolin automatically creates a copy of the database file before a migration runs so you can roll back if needed. You can disable this by setting the `DISABLE_BACKUP_ON_MIGRATION` environment variable to `true`.

<Warning>
  Because migrations can change the database schema, downgrading is sometimes impossible and is not recommended. The database may become incompatible with older versions. Always back up your database before updating.
</Warning>

## Before You Update

<Warning>
  **Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
</Warning>

<Tip>
  **Recommended**: Update incrementally between major versions. For example, update from 1.0.0 > 1.1.0 > 1.2.0 instead of jumping directly from 1.0.0 > 1.2.0.
</Tip>

## Update Process

<Steps>
  <Step title="Stop the stack">
    Stop all running containers:

    ```bash theme={null}
    sudo docker compose down
    ```
  </Step>

  <Step title="Check latest versions">
    Find the latest version numbers:

    * **Pangolin**: [GitHub Releases](https://github.com/fosrl/pangolin/releases)
    * **Gerbil**: [GitHub Releases](https://github.com/fosrl/gerbil/releases)
    * **Traefik**: [Docker Hub](https://github.com/traefik/traefik/releases)
    * **Badger**: [GitHub Releases](https://github.com/fosrl/badger/releases)

    <Info>
      Look for the latest stable release (not pre-release or beta versions).
    </Info>
  </Step>

  <Step title="Update version numbers">
    Edit your `docker-compose.yml` file and update the image versions:

    ```yaml title="docker-compose.yml" theme={null}
    services:
      pangolin:
          image: fosrl/pangolin:1.22.0 # Check GitHub Releases for latest version tag
          # ... rest of config

      gerbil:
          image: fosrl/gerbil:1.5.1 # Check GitHub Releases for latest version tag
          # ... rest of config
      
        traefik:
          image: traefik:v3.7.12 # Check GitHub Releases for latest version tag
          # ... rest of config
    ```

    Increase the Badger version number in `config/traefik/traefik_config.yml`:

    ```yaml title="traefik_config.yml" theme={null}
    experimental:
      plugins:
        badger:
          moduleName: github.com/fosrl/badger
          version: v1.7.0 # Check GitHub Releases for latest version tag
    ```

    <Warning>
      Update each service you want to upgrade. You can update them individually or all at once.
    </Warning>
  </Step>

  <Step title="Pull new images">
    Download the updated Docker images:

    ```bash theme={null}
    sudo docker compose pull
    ```
  </Step>

  <Step title="Start the stack">
    Start the updated containers:

    ```bash theme={null}
    sudo docker compose up -d
    ```
  </Step>

  <Step title="Monitor the update">
    Watch the logs to ensure everything starts correctly:

    ```bash theme={null}
    sudo docker compose logs -f
    ```
  </Step>

  <Step title="Verify functionality">
    Test that everything is working:

    1. Access your Pangolin dashboard
    2. Check that all sites are accessible
    3. Verify tunnel connections (if using Gerbil)
    4. Test any custom configurations

    <Check>
      If everything works, your update is complete!
    </Check>
  </Step>
</Steps>