Skip to main content

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.

EditionDeployment Type
EnterpriseSelf-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:
  1. 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.
  2. 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).
  3. 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.
    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.
  4. 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.

​
Docker

​
Docker Run

  1. Stop and remove the running Portal container. 
    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. 
    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. 
    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. 
    docker logs tyk-portal

​
Docker Compose

  1. Update the Portal image tag in your docker-compose.yaml file: 
    tyk-portal:
  image: tykio/portal:<NEW_VERSION>
  2. Pull the new image and restart the Portal container. 
    docker-compose pull tyk-portal
docker-compose up -d tyk-portal
  3. Verify the Portal has started successfully. 
    docker-compose logs tyk-portal

​
Kubernetes

Developer Portal Helm Chart (tyk-dev-portal)
  1. Update the Portal image tag in your values.yaml: 
    image:
  tag: "<NEW_VERSION>"
  2. Run the Helm upgrade. 
    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, update global.components.devPortal.image.tag and run: 
    helm upgrade tyk tyk-helm/tyk-stack \
  -f values.yaml \
  -n tyk
  3. Watch the rollout. 
    kubectl rollout status deployment/<portal-deployment-name> -n tyk
  4. Check the logs for startup errors. 
    kubectl logs -f <portal-pod-name> -n tyk
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.

​
Linux

​
Red Hat / CentOS

  1. Download the new Portal RPM package from packagecloud.io. Replace <VERSION> with the target version. 
    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. 
    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. 
    sudo systemctl restart portal.service
  5. Check the service status. 
    systemctl status portal.service

​
Ubuntu / Debian

  1. Download the new Portal DEB package from packagecloud.io. Replace <VERSION> with the target version. 
    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. 
    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. 
    sudo systemctl restart portal.service
  5. Check the service status. 
    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 for the full procedure.
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.

​
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.
  1. 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.
  2. Consumer login works. Open the Live Portal and verify that existing API Consumer users can log in.
  3. API Catalog is visible. Confirm that published API Products are visible to users on the Live Portal.
  4. Theme renders correctly. Check the Live Portal for visual regressions or template errors in the browser console.
  5. 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.
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.

​
Docker

  1. Stop and remove the upgraded container. 
    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. 
    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: 
    helm history tyk-dev-portal -n tyk
    Then roll back to the previous revision: 
    helm rollback tyk-dev-portal -n tyk
    To roll back to a specific revision number: 
    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: 
    sudo apt-get install tyk-portal=<PREVIOUS_VERSION>
    On Red Hat / CentOS: 
    sudo yum downgrade tyk-portal-<PREVIOUS_VERSION>
  3. Restart the Portal service. 
    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.