> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/maintenance/zip-migration-guide.md).

# ZIP installation migration guide

ZIP installation is still available, but it will be removed in a future release. This guide helps you migrate your SonarQube Community Build instance to a container-based deployment.

## Introduction <a href="#introduction" id="introduction"></a>

We recommend installing SonarQube Community Build with the Docker image or the Helm chart. ZIP installation is still available, but it will be removed in a future release. See the [deprecation policy](https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/maintenance/deprecations/deprecation-policy.md) for details.

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

* [From Docker image](https://docs.sonarsource.com/sonarqube-community-build/server-installation/from-docker-image.md): Suited to single-host deployments.
* [On Kubernetes or OpenShift](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift.md): Suited to teams that already run Kubernetes or OpenShift.

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.

## How the migration works <a href="#how-it-works" id="how-it-works"></a>

All your SonarQube Community Build data (projects, issues, quality profiles and gates, users, permissions, and settings) 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 <a href="#before-you-start" id="before-you-start"></a>

* **Use the same SonarQube Community Build version**: Deploy the container image or Helm chart that matches your ZIP version exactly, including the build number, for example `sonarqube:26.10.0.133078-community` for a ZIP 26.10.0.133078. 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](https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/update.md).
* **Use an external database**: If your ZIP instance uses the embedded H2 database, you cannot migrate it. See [H2 database not recommended in production](https://docs.sonarsource.com/sonarqube-community-build/server-installation/installing-the-database.md#h2-database-not-recommended-in-production).
* **Back up your database**: See [Backup and restore](https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/maintenance/backup-and-restore.md). 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 Community Build 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. 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. The Server ID identifies your instance, and you need it to get a license if you later move to a commercial edition of SonarQube Server. See [System info and server ID](https://docs.sonarsource.com/sonarqube-community-build/instance-administration/system-info-and-server-id.md) for more information. Do not replace the database host with an IP address or `host.docker.internal` unless a new Server ID is acceptable to you.

  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.

{% hint style="info" %}
If the Server ID was reset by mistake, set the original JDBC URL back and restart. The original Server ID is restored.
{% endhint %}

## What to carry over <a href="#what-to-carry-over" id="what-to-carry-over"></a>

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](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/customizing-helm-chart.md#sonar-secret-properties). |
| Other properties (for example `sonar.web.javaOpts`, LDAP, proxy). See [List of system properties](https://docs.sonarsource.com/sonarqube-community-build/server-installation/system-properties/system-properties.md) for each property. The environment variable is the property name in uppercase, with dots replaced by underscores. | 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](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/customizing-helm-chart.md#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 Community Build 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](https://docs.sonarsource.com/sonarqube-community-build/instance-administration/security/encrypting-settings.md) and [Encrypting Helm chart sensitive data](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/encrypting-helm-chart-sensitive-data.md).
* **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](https://docs.sonarsource.com/sonarqube-community-build/server-installation/pre-installation/jwt-token.md).
* **Plugins**: Check that each plugin is compatible with your version. See [Plugin version matrix](https://docs.sonarsource.com/sonarqube-community-build/server-installation/plugins/plugin-version-matrix.md).
* **Oracle**: If you use an Oracle database, the container needs the JDBC driver. Without it, SonarQube Community Build 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 <a href="#migrate-to-docker" id="migrate-to-docker"></a>

1. Prepare the Docker host. See [Prepare the Docker installation](https://docs.sonarsource.com/sonarqube-community-build/server-installation/from-docker-image/prepare-installation.md). On Linux, set the kernel limits required by Elasticsearch and make them persistent:

   ```bash
   sudo sysctl -w vm.max_map_count=524288
   sudo sysctl -w fs.file-max=131072
   printf 'vm.max_map_count=524288\nfs.file-max=131072\n' | sudo tee /etc/sysctl.d/99-sonarqube.conf
   ```
2. Create the volumes and copy your plugins, and your Oracle JDBC driver if you use Oracle, into the extensions volume:

   ```bash
   docker volume create sonarqube_data
   docker volume create sonarqube_extensions
   docker volume create sonarqube_logs

   docker run --rm -v sonarqube_extensions:/ext -v $SONARQUBE_HOME/extensions:/src:ro alpine sh -c '
     mkdir -p /ext/plugins && cp /src/plugins/*.jar /ext/plugins/
     if [ -d /src/jdbc-driver/oracle ]; then mkdir -p /ext/jdbc-driver/oracle && cp /src/jdbc-driver/oracle/*.jar /ext/jdbc-driver/oracle/; fi
     chown -R 1000:0 /ext'
   ```
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:

   ```bash
   sudo systemctl stop sonarqube
   sudo systemctl disable sonarqube
   ```
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](#before-you-start).

{% tabs %}
{% tab title="docker run" %}

```bash
docker run -d --name sonarqube --restart unless-stopped -p 9000:9000 \
  --ulimit nofile=131072:131072 --ulimit nproc=8192:8192 \
  -e SONAR_JDBC_URL="<same value as sonar.jdbc.url>" \
  -e SONAR_JDBC_USERNAME="<sonar.jdbc.username>" \
  -e SONAR_JDBC_PASSWORD="<sonar.jdbc.password, encrypted value accepted>" \
  -e SONAR_SECRETKEYPATH=/opt/sonarqube/secret/sonar-secret.txt \
  -e SONAR_AUTH_JWTBASE64HS256SECRET="<sonar.auth.jwtBase64Hs256Secret>" \
  -v /etc/sonarqube/sonar-secret.txt:/opt/sonarqube/secret/sonar-secret.txt:ro \
  -v sonarqube_data:/opt/sonarqube/data \
  -v sonarqube_extensions:/opt/sonarqube/extensions \
  -v sonarqube_logs:/opt/sonarqube/logs \
  sonarqube:<same-version>-community
```

{% endtab %}

{% tab title="Docker Compose" %}

```yaml
services:
  sonarqube:
    image: sonarqube:<same-version>-community
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      SONAR_JDBC_URL: "<same value as sonar.jdbc.url>"
      SONAR_JDBC_USERNAME: "<sonar.jdbc.username>"
      SONAR_JDBC_PASSWORD: ${SONAR_JDBC_PASSWORD}   # from a .env file; encrypted value accepted
      SONAR_SECRETKEYPATH: /run/secrets/sonar-secret.txt
      SONAR_AUTH_JWTBASE64HS256SECRET: ${SONAR_AUTH_JWTBASE64HS256SECRET}
    secrets:
      - sonar-secret.txt
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    ulimits:
      nofile:
        soft: 131072
        hard: 131072
      nproc: 8192
secrets:
  sonar-secret.txt:
    file: /etc/sonarqube/sonar-secret.txt
volumes:
  sonarqube_data:
    external: true
  sonarqube_extensions:
    external: true
  sonarqube_logs:
    external: true
```

```bash
docker compose up -d
```

{% endtab %}
{% endtabs %}

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

   ```bash
   docker logs -f sonarqube
   ```
7. [Verify the migration](#verify).

## Migrate to Kubernetes or OpenShift <a href="#migrate-to-kubernetes" id="migrate-to-kubernetes"></a>

1. Check the prerequisites in [Before you start](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/before-you-start.md).
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](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/set-up-monitoring/prometheus.md) for more information.

   ```bash
   kubectl create namespace sonarqube
   helm repo add sonarqube https://SonarSource.github.io/helm-chart-sonarqube
   helm repo update
   kubectl -n sonarqube create secret generic sonar-secret-key \
     --from-file=sonar-secret.txt=<path to your sonar-secret.txt>
   kubectl -n sonarqube create secret generic sonar-jdbc \
     --from-literal=jdbc-password='<sonar.jdbc.password, encrypted value accepted>'
   kubectl -n sonarqube create secret generic sonar-secret-props \
     --from-literal=secret.properties='sonar.auth.jwtBase64Hs256Secret=<value>'
   kubectl -n sonarqube create secret generic sonar-monitoring \
     --from-literal=passcode='<monitoring passcode>'
   ```
3. Create a `values.yaml` file:

   ```yaml
   community:
     enabled: true
     buildNumber: "<same build number as your ZIP version>"
   monitoringPasscodeSecretName: sonar-monitoring
   monitoringPasscodeSecretKey: passcode
   jdbcOverwrite:
     enabled: true
     jdbcUrl: "<same value as sonar.jdbc.url>"
     jdbcUsername: "<sonar.jdbc.username>"
     jdbcSecretName: sonar-jdbc
     jdbcSecretPasswordKey: jdbc-password
     # Oracle only: the driver is downloaded at startup
     # oracleJdbcDriver:
     #   url: "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/<version>/ojdbc11-<version>.jar"
   sonarSecretKey: sonar-secret-key
   sonarSecretProperties: sonar-secret-props
   sonarProperties:
     sonar.web.javaOpts: "<value from sonar.properties>"
   plugins:
     install:
       - "<download URL of each plugin>"
   ```

   `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 Community Build runs three processes in the pod.

   On OpenShift, set `OpenShift.enabled: true` in `values.yaml`. See [Example: installing on OpenShift](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/installing-helm-chart.md#openshift-test) for more information.
4. Stop the ZIP instance and make sure it cannot restart.
5. Install the chart. `community.buildNumber` deploys the same version as your ZIP installation. See [Installing Helm chart](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/installing-helm-chart.md).

   ```bash
   helm upgrade --install -n sonarqube sonarqube sonarqube/sonarqube -f values.yaml
   ```
6. Follow the logs until you see `SonarQube is operational`:

   ```bash
   kubectl -n sonarqube logs -f sonarqube-sonarqube-0 -c sonarqube
   ```
7. [Verify the migration](#verify).

## Verify the migration <a href="#verify" id="verify"></a>

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: …`).
3. The background indexing has finished (**Administration** > **Projects** > **Background tasks**). After it finishes, your projects, issues, and issue statuses (confirmed, 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 <a href="#roll-back" id="roll-back"></a>

As long as you used the same SonarQube Community Build 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.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Set up and start your container](https://docs.sonarsource.com/sonarqube-community-build/server-installation/from-docker-image/set-up-and-start-container.md)
* [Customizing Helm chart](https://docs.sonarsource.com/sonarqube-community-build/server-installation/on-kubernetes-or-openshift/customizing-helm-chart.md)
* [Backup and restore](https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/maintenance/backup-and-restore.md)
* [Sensitive settings](https://docs.sonarsource.com/sonarqube-community-build/instance-administration/security/encrypting-settings.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-community-build/server-update-and-maintenance/maintenance/zip-migration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
