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

# Developer Portal Upgrade Guide

> Step-by-step instructions for upgrading the Tyk Developer Portal across Docker, Kubernetes, and Linux deployments.

| Edition    | Deployment Type             |
| :--------- | :-------------------------- |
| Enterprise | Self-Managed, Hybrid, Cloud |

This guide explains how to upgrade the Tyk Developer Portal to a new version. The upgrade process involves replacing the Portal binary or container image, after which the Portal automatically applies any required database migrations on startup. You must also manually upgrade your theme to pick up template changes.

## Before You Upgrade

Complete the following steps before starting the upgrade:

2. **Review the release notes** for every version between your current version and the target version. Pay particular attention to the "Breaking Changes" section. See [Portal Release Notes](/5.12/developer-support/release-notes/portal).

3. **Back up your database.** The Portal stores its configuration and Product, Plan, and Developer data in the database. Use the native backup utility for your database engine (PostgreSQL, MySQL, or MariaDB).

4. **Back up your theme files.** If you have a custom theme, export it from the Admin Portal or copy the theme directory before upgrading. See [Upgrade Your Theme](/5.12/#upgrade-your-theme).

   <Warning>
     Skipping the theme upgrade after a Portal version bump can cause template rendering errors, UI breakages on the Live Portal, or failed authentication flows. Always upgrade your theme as part of the Portal upgrade process.
   </Warning>

5. **Note your current Portal version.** You can find this in the Admin Portal under the account settings, or by checking the running container image tag.

## Upgrade Procedure

### Tyk Cloud

On Tyk Cloud, the Developer Portal upgrade is managed through the Tyk Cloud Console. You do not run Docker or Kubernetes commands directly.

1. **Open the Tyk Cloud Console** and navigate to your deployment settings.

2. **Select the target Portal version** from the **version** dropdown.

3. **Apply the update.**

   Tyk Cloud orchestrates the rolling upgrade of the underlying infrastructure on your behalf. Database migrations run automatically during this process.

   After the upgrade completes, proceed to [Post-Upgrade Verification](/5.12/#post-upgrade-verification).

### Docker

#### Docker Run

1. **Stop and remove the running Portal container.**

   ```console theme={null}
   docker stop tyk-portal
   docker rm tyk-portal
   ```

2. **Pull the new Portal image.** Replace `<NEW_VERSION>` with the target version, for example `v1.17.1`. You can browse all available versions on [Docker Hub](https://hub.docker.com/r/tykio/portal/tags).

   ```console theme={null}
   docker pull tykio/portal:<NEW_VERSION>
   ```

3. **Start the Portal container using the new image.** Use the same `docker run` command from your initial installation, updating only the image tag. The Portal applies any required database migrations automatically on startup.

   ```console theme={null}
   docker run -d \
       -p 3001:3001 \
       --env-file .env \
       --network tyk-portal \
       --name tyk-portal \
       tykio/portal:<NEW_VERSION>
   ```

4. **Verify the Portal has started successfully.** Confirm there are no startup errors before proceeding to post-upgrade verification.

   ```console theme={null}
   docker logs tyk-portal
   ```

#### Docker Compose

1. **Update the Portal image tag** in your `docker-compose.yaml` file:

   ```yaml theme={null}
   tyk-portal:
     image: tykio/portal:<NEW_VERSION>
   ```

2. **Pull the new image and restart the Portal container.**

   ```console theme={null}
   docker-compose pull tyk-portal
   docker-compose up -d tyk-portal
   ```

3. **Verify the Portal has started successfully.**

   ```console theme={null}
   docker-compose logs tyk-portal
   ```

### Kubernetes

[Developer Portal Helm Chart](https://github.com/TykTechnologies/tyk-charts/tree/main/components/tyk-dev-portal) (`tyk-dev-portal`)

1. **Update the Portal image tag** in your `values.yaml`:

   ```yaml theme={null}
   image:
     tag: "<NEW_VERSION>"
   ```

2. **Run the Helm upgrade.**

   ```console theme={null}
   helm upgrade tyk-dev-portal tyk-helm/tyk-dev-portal \
     -f values.yaml \
     -n tyk
   ```

   If the Portal is deployed as part of the full [Tyk Stack chart](https://github.com/TykTechnologies/tyk-charts/tree/main/tyk-stack), update `global.components.devPortal.image.tag` and run:

   ```console theme={null}
   helm upgrade tyk tyk-helm/tyk-stack \
     -f values.yaml \
     -n tyk
   ```

3. **Watch the rollout.**

   ```console theme={null}
   kubectl rollout status deployment/<portal-deployment-name> -n tyk
   ```

4. **Check the logs for startup errors.**

   ```console theme={null}
   kubectl logs -f <portal-pod-name> -n tyk
   ```

<Note>
  If the Portal pod restarts before startup completes, particularly after a theme upgrade, increase the `initialDelaySeconds` value in your readiness and liveness probe configuration to at least 60 seconds.

  A smaller value may cause Kubernetes to mark the pod as unhealthy and restart it before the application has finished initializing.
</Note>

### Linux

#### Red Hat / CentOS

1. **Download the new Portal RPM package** from [packagecloud.io](https://packagecloud.io/tyk/portal). Replace `<VERSION>` with the target version.

   ```console theme={null}
   wget --content-disposition "https://packagecloud.io/tyk/portal/packages/<distro-type>/<distro-version>/portal_<VERSION>_1.x86_64.rpm/download.rpm?distro_version_id=284"
   ```

2. **Upgrade the installed package.**

   ```console theme={null}
   sudo rpm -Uvh portal-<VERSION>-1.x86_64.rpm
   ```

3. **Review the Portal configuration file** at `/opt/portal/portal.conf`. Consult the release notes for any changes to configuration options required by the new version.

4. **Restart the Portal service.**

   ```console theme={null}
   sudo systemctl restart portal.service
   ```

5. **Check the service status.**

   ```console theme={null}
   systemctl status portal.service
   ```

#### Ubuntu / Debian

1. **Download the new Portal DEB package** from [packagecloud.io](https://packagecloud.io/tyk/portal). Replace `<VERSION>` with the target version.

   ```console theme={null}
   wget --content-disposition "https://packagecloud.io/tyk/portal/packages/<distro-type>/<distro-version>/portal_<VERSION>_amd64.deb/download.deb?distro_version_id=284"
   ```

2. **Install the new package.** `dpkg -i` replaces the existing installation.

   ```console theme={null}
   sudo dpkg -i portal_<VERSION>_amd64.deb
   ```

3. **Review the Portal configuration file** at `/opt/portal/portal.conf`. Consult the release notes for any changes to configuration options required by the new version.

4. **Restart the Portal service.**

   ```console theme={null}
   sudo systemctl restart portal.service
   ```

5. **Check the service status.**

   ```console theme={null}
   systemctl status portal.service
   ```

## Upgrade Your Theme

To prevent from accidentally overwriting your customizations, the Developer Portal does not automatically update the default theme when the Portal is upgraded. After every Portal upgrade, you must check whether the new version includes theme changes and merge them into your custom theme.

See [Upgrading Themes](/5.12/portal/customization/themes#upgrading-themes) for the full procedure.

<Warning>
  Skipping the theme upgrade after a Portal version bump can cause template rendering errors, UI breakages on the Live Portal, or failed authentication flows. Always upgrade your theme as part of the portal upgrade process.
</Warning>

## Post-Upgrade Verification

After the Portal has started, confirm the following before directing traffic to the upgraded instance:

1. **Admin Portal is accessible.** Log in at `http://<your-portal-host>:<port>/portal-admin`.

2) **Provider sync is working.** Navigate to **Providers** in the Admin Portal and confirm your Providers show a healthy sync status. If sync fails after upgrade, check whether any policies in Tyk Dashboard reference API IDs that no longer exist. A stale policy referencing a deleted API will abort the entire sync. Delete or correct the affected policy and re-trigger sync. See also [Troubleshooting > Upgrade Failures](/5.12/portal/troubleshooting/upgrade-failures).

3) **Consumer login works.** Open the Live Portal and verify that existing API Consumer users can log in.

4) **API Catalog is visible.** Confirm that published API Products are visible to users on the Live Portal.

5) **Theme renders correctly.** Check the Live Portal for visual regressions or template errors in the browser console.

6) **Review the Portal logs.** Look for any `ERROR` or `WARN` messages that indicate a migration or configuration issue.

## Rollback Procedure

If the upgrade causes issues that you cannot resolve, roll back to the previous version using the steps below.

<Warning>
  A rollback involves restoring the database backup taken before the upgrade. Any data changes made after the upgrade, including new users, access requests, and configuration updates, will be lost.
</Warning>

### Docker

1. **Stop and remove the upgraded container.**

   ```console theme={null}
   docker stop tyk-portal
   docker rm tyk-portal
   ```

2. **Restore the database** from the backup you took before the upgrade.

3. **Start the Portal using the previous image tag.**

   ```console theme={null}
   docker run -d \
       -p 3001:3001 \
       --env-file .env \
       --network tyk-portal \
       --name tyk-portal \
       tykio/portal:<PREVIOUS_VERSION>
   ```

### Kubernetes

1. **Restore the database** from the backup you took before the upgrade.

2. **Roll back the Helm release.** First, list available revisions:

   ```console theme={null}
   helm history tyk-dev-portal -n tyk
   ```

   Then roll back to the previous revision:

   ```console theme={null}
   helm rollback tyk-dev-portal -n tyk
   ```

   To roll back to a specific revision number:

   ```console theme={null}
   helm rollback tyk-dev-portal <REVISION_NUMBER> -n tyk
   ```

### Linux

1. **Restore the database** from the backup taken before the upgrade.

2. **Downgrade the package** to the previous version.

   On Ubuntu / Debian:

   ```console theme={null}
   sudo apt-get install tyk-portal=<PREVIOUS_VERSION>
   ```

   On Red Hat / CentOS:

   ```console theme={null}
   sudo yum downgrade tyk-portal-<PREVIOUS_VERSION>
   ```

3. **Restart the Portal service.**

   ```console theme={null}
   sudo systemctl restart portal.service
   ```

## Common Upgrade Issues

For detailed troubleshooting steps for common upgrade failure scenarios, including Admin Portal inaccessible after upgrade, broken Product and Plan sync, and user login failures, see [Troubleshooting > Upgrade Failures](/5.12/portal/troubleshooting/upgrade-failures).