Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

ZIP installation migration guide

ZIP installation is still supported, but it will be removed in a future release. This guide helps you move SonarQube Server to a container-based deployment. This page is for SonarQube Server 2026.5.

Introduction

We recommend installing SonarQube Server with the Docker image or the Helm chart. ZIP installation is still supported, but it will be removed in a future release. See the deprecation policy for details.

We recommend migrating to a containerized deployment. Containers give you a consistent, reproducible environment, simplify updates, and run the agentic features natively. Choose the option that fits your infrastructure:

This guide walks you through switching your existing ZIP installation to the deployment option you choose. Your data stays in your existing database: you carry over your configuration, start the container against the same database, verify the result, and roll back if needed. The guide also covers Data Center edition clusters.

How the migration works

All your SonarQube Server data (projects, issues, quality profiles and gates, users, permissions, settings, and license) is stored in the database. The migration does not move that data: you stop the ZIP instance and start a container that connects to the same database.

The container rebuilds its search index from the database at first start. You do not copy the ZIP's data directory.

Before you start

  • Use the same SonarQube Server version: Deploy the container image or Helm chart that matches your ZIP version exactly, for example sonarqube:2026.5.2-enterprise for a ZIP 2026.5.2. Do not combine the migration with an update. If you also want to update, do it as a separate step before or after the migration. See Update.

  • Use an external database: If your ZIP instance uses the embedded H2 database, you cannot migrate it. See H2 database not recommended in production.

  • Back up your database: See Backup and restore. It's your rollback point if something goes wrong.

  • Check that the database is reachable: Make sure the container network can reach the database, using the hostname you plan to use. See the Keep the JDBC URL identical requirement for more information.

  • Keep the JDBC URL identical: SonarQube Server computes its Server ID from the database and the JDBC URL. If the URL string changes, even if it still points to the same database (for example localhost to a service name or an IP address), the Server ID is reset at startup and your license becomes invalid. The log shows:

    Server ID is reset because it is not valid anymore. Database URL probably changed. The new server ID affects SonarSource licensed products.

    Moving to a container does not change the Server ID by itself; only a different JDBC URL does. Do not replace the database host with an IP address or host.docker.internal unless you plan to request a new license.

    If the hostname in your URL does not resolve from the new environment, make it resolve to the database there, for example with --add-host (Docker), extra_hosts (Docker Compose), or hostAliases or an ExternalName Service (Kubernetes).

    If your URL uses localhost (database on the same host as the ZIP instance), localhost inside a container points to the container itself:

    • Docker on Linux: Run the container with host networking (--network host, or network_mode: host in Docker Compose). localhost then reaches the database on the host and the URL stays the same.

    • Kubernetes: A pod cannot reach the database through localhost. You must change the URL, which resets the Server ID. Request a new license for the new Server ID.

If the Server ID was reset by mistake, set the original JDBC URL back and restart. The original Server ID is restored.

What to carry over

Go through your $SONARQUBE_HOME/conf/sonar.properties, $SONARQUBE_HOME/extensions/, and any environment variables set on the ZIP host. Every non-default setting must be moved to the new deployment.

ZIP installation
Docker
Kubernetes (Helm chart)

sonar.jdbc.url, sonar.jdbc.username

SONAR_JDBC_URL, SONAR_JDBC_USERNAME

jdbcOverwrite.enabled: true, jdbcOverwrite.jdbcUrl, jdbcOverwrite.jdbcUsername

sonar.jdbc.password (plain or {aes-gcm} encrypted)

SONAR_JDBC_PASSWORD

Kubernetes secret referenced by jdbcOverwrite.jdbcSecretName and jdbcOverwrite.jdbcSecretPasswordKey

Encryption key (~/.sonar/sonar-secret.txt or sonar.secretKeyPath)

Mount the file and set SONAR_SECRETKEYPATH

Kubernetes secret with the key sonar-secret.txt, referenced by sonarSecretKey

sonar.auth.jwtBase64Hs256Secret

SONAR_AUTH_JWTBASE64HS256SECRET

sonarSecretProperties (secret with the key secret.properties). See Storing sensitive properties in a secret.

Other properties (for example sonar.web.javaOpts, LDAP, proxy). See List of properties common to all editions for each property and its environment variable.

The property's environment variable, for example SONAR_WEB_JAVAOPTS

sonarProperties, or sonarSecretProperties for sensitive values

Plugins in extensions/plugins

Copy the JAR files to the extensions volume

plugins.install (list of download URLs). See Installing plugins.

Oracle JDBC driver in extensions/jdbc-driver/oracle

Copy the JAR file to jdbc-driver/oracle in the extensions volume

jdbcOverwrite.oracleJdbcDriver.url (download URL of the driver)

data/ directory

Do not copy. Use an empty data volume.

Do not copy.

logs/, temp/

Do not copy.

Do not copy.

Notes:

  • Encrypted settings: If any setting, in sonar.properties or in the database, is encrypted ({aes-gcm}… or {aes}…), you must bring the same encryption key. Without it, SonarQube Server cannot decrypt the database password and stops at startup with Fail to decrypt the property sonar.jdbc.password. Please check your secret key. Encrypted values can be passed unchanged through environment variables and Kubernetes secrets. See Sensitive settings and Encrypting Helm chart sensitive data.

  • JWT secret: If you set sonar.auth.jwtBase64Hs256Secret on the ZIP instance, reuse the same value so that users stay logged in. If you did not set it, users have to log in again after the migration. See Defining a JWT token.

  • Plugins: Check that each plugin is compatible with your version. See Plugin version matrix.

  • Oracle: If you use an Oracle database, the container needs the JDBC driver. Without it, SonarQube Server stops at startup with Directory does not exist: extensions/jdbc-driver/oracle.

  • Container user (Docker): The Docker container runs as user ID 1000. Files you mount or copy (encryption key, plugins, JDBC driver) must be readable by that user. On Kubernetes and OpenShift, these come from secrets or are downloaded at startup, so this does not apply.

Migrate to Docker

  1. Prepare the Docker host. See Prepare the Docker installation. On Linux, set the kernel limits required by Elasticsearch and make them persistent:

  2. Create the volumes and copy your plugins, and your Oracle JDBC driver if you use Oracle, into the extensions volume:

  3. Copy the encryption key to the Docker host, for example to /etc/sonarqube/sonar-secret.txt, readable by user ID 1000.

  4. Stop the ZIP instance and make sure it cannot restart, for example:

  5. Start the container with the same JDBC URL and the settings you collected, using docker run or Docker Compose. If your JDBC URL uses localhost, replace the port mapping with --network host (or network_mode: host). See Before you start.

  1. Follow the logs until you see SonarQube is operational:

Migrate to Kubernetes or OpenShift

  1. Check the prerequisites in Before you start.

  2. Create the namespace, add the Helm repository, and create the secrets. The Helm chart requires a monitoring passcode, so you also create a secret for it. See Setting up with Prometheus server for more information.

  3. Create a values.yaml file:

    plugins.install and oracleJdbcDriver.url download the files at startup, so the pod needs network access to the URLs. For plugins, use the download URL of the plugin version you run, from the plugin's release page. If the cluster has no access to these URLs, build a custom image that includes your plugins. Keep the default resources unless you have sized them deliberately: SonarQube Server runs three processes in the pod.

    On OpenShift, set OpenShift.enabled: true in values.yaml. See Example: installing on OpenShift for more information.

  4. Stop the ZIP instance and make sure it cannot restart.

  5. Install the chart version that matches your ZIP version. See Installing Helm chart.

  6. Follow the logs until you see SonarQube is operational:

Verify the migration

  1. The logs show SonarQube is operational and GET /api/system/status returns UP. The instance must not ask for a database migration (status DB_MIGRATION_NEEDED, or the /setup page). If it does, the image version does not match your ZIP version. Do not start the database migration. Stop the container and deploy the matching version.

  2. The log shows the same Server ID as the ZIP instance (Server ID: …), and Administration > Configuration > License manager shows a valid license.

  3. The background indexing has finished (Administration > Projects > Background tasks). After it finishes, your projects, issues, and issue statuses (accepted, false positive) are visible as before.

  4. Users can log in. Plugins are listed in Administration > Marketplace > Installed.

  5. Run an analysis from your CI pipeline and check that it succeeds.

After you verify everything, update your DNS, reverse proxy, or load balancer to point to the new deployment, then decommission the ZIP host.

Roll back

As long as you used the same SonarQube Server version, you can go back to the ZIP instance:

  1. Stop the container (or helm uninstall).

  2. Delete the ZIP instance's $SONARQUBE_HOME/data/es* directory, so that the search index is rebuilt from the database and includes the changes made while the container was running.

  3. Start the ZIP instance.

If the database itself is damaged, restore your backup before you start the ZIP instance.

Data Center edition

A ZIP cluster migrates with the same procedure as a single instance. The differences:

  • Stop every node of the ZIP cluster: Stop the application and search nodes before you start the new cluster. Do not run ZIP nodes and container nodes in the same cluster.

  • Carry over the settings of the application nodes: Use the same JDBC URL, the same encryption key, and the same JWT secret on every application node. They're already identical across your ZIP application nodes.

  • Do not copy the data of the search nodes: The new search nodes start empty and the index is rebuilt from the database.

  • Plugins and the Oracle JDBC driver: They're needed on the application nodes only.

  • Use the Data Center edition images (sonarqube:<same-version>-datacenter-app and sonarqube:<same-version>-datacenter-search) or the sonarqube-dce Helm chart.

Follow the procedure in From Docker image. Running all the nodes on a single Docker host is for testing only. Compared to the single-instance example in Migrate to Docker:

  • Application nodes: the same SONAR_JDBC_*, SONAR_SECRETKEYPATH, and SONAR_AUTH_JWTBASE64HS256SECRET variables, plus SONAR_CLUSTER_SEARCH_HOSTS (your search nodes) and SONAR_CLUSTER_HOSTS (your application nodes). Copy your plugins into an extensions volume shared by the application nodes, with the same command as in step 2.

  • Search nodes: SONAR_CLUSTER_ES_HOSTS (all search nodes) and SONAR_CLUSTER_NODE_NAME, each with a new, empty data volume.

  • Start the search nodes first, then the application nodes.

For each cluster property and its environment variable, see List of DCE-specific properties.

Use the sonarqube-dce chart. See Installing the DCE Helm chart. Run the commands from step 2 of Migrate to Kubernetes or OpenShift to create the namespace, add the Helm repository, and create the secrets, except the JWT secret. The chart reads the JWT secret from its own key:

The values differ from the single-instance chart: there's no edition value, and the application settings are under applicationNodes:

This example uses existingJwtSecret so that the JWT secret is not stored in plain text in values.yaml. You can also set applicationNodes.jwtSecret directly.

Keep the default resources of applicationNodes and searchNodes unless you have sized them deliberately.

On OpenShift, set OpenShift.enabled: true in values.yaml. See Example: installing on OpenShift for more information.

When you verify the migration, also check that Administration > System lists all application and search nodes, and that GET /api/system/health returns GREEN.

To roll back, stop the new cluster and delete $SONARQUBE_HOME/data/es* on every ZIP search node before you start the ZIP cluster: search nodes first, then application nodes.

Last updated

Was this helpful?