JetBrains Space Help

Upgrade from Earlier Versions

Space On-Premises supports only forward updates – it's not possible to downgrade to previous versions. The way you should update your Space instance depends on whether it's a minor or a major update.

Minor updates

These updates change the minor Space version, for example, from 2023.1.0 to 2023.1.1. Such updates don't bring any significant changes and typically include bug fixes and security patches.

The instructions imply that your Space On-Premises instance is installed to the space-on-premises directory.

  1. Open the Space installation directory:

    cd space-on-premises

  2. Download the latest version of the docker-compose.yml file from https://assets.on-premises.service.jetbrains.space/. For example, if the latest version is 2023.3.0:

    export SPACE_RELEASE_NAME="2023.3.0" curl -O "https://assets.on-premises.service.jetbrains.space/${SPACE_RELEASE_NAME}/docker-compose.yml"

  3. If you have customized docker-compose.yml for your previous Space version, apply the corresponding changes to the new docker-compose.yml.

  4. Restart your Space instance:

    docker-compose -p space-on-premises up

  1. Update local data on chart repositories:

    helm repo update

  2. Upgrade the Helm release:

    helm -n ${KUBE_NAMESPACE} upgrade ${SPACE_RELEASE_NAME} ${HELM_REPO}/${CHART_NAME} -f values.yaml

    Here values.yaml is the values file of your current Space On-Premises instance.

Major updates

These updates change the major Space version, for example, from 2023.1.1 to 2023.2.0, or from 2023.3.0 to 2024.1.0. Such updates bring new features and might require changes in databases and infrastructure configuration. To perform a major update, you should migrate Space data as described in this section.

Migration cannot be performed without downtime, as it requires a complete shutdown of the old version before running the new one. Make sure to plan the maintenance window and inform your users about the upcoming activities.

Before migration

Before starting the migration, we strongly recommend that you back up your Space data. Here you can find the primary considerations of what you should back up.

How to migrate

The data migration process differs for the Docker Compose and Kubernetes installations.

For simplicity, the instructions imply that your current Space On-Premises instance is installed to the space-on-premises-oldversion directory. The new Space On-Premises instance will be installed to the space-on-premises-newversion directory.

  1. Create and open an installation directory for the new Space instance:

    mkdir -p space-on-premises-newversion && cd space-on-premises-newversion

  2. Download the latest version of the docker-compose.yml file from https://assets.on-premises.service.jetbrains.space/. For example, if the latest version is 2023.3.0:

    export SPACE_RELEASE_NAME="2023.3.0" curl -O "https://assets.on-premises.service.jetbrains.space/${SPACE_RELEASE_NAME}/docker-compose.yml"

  3. If you have customized docker-compose.yml for your previous Space version, apply the corresponding changes to the new docker-compose.yml.

  4. Migration requires editing Space configuration files, meaning that the files must be copied from a Space container to the host machine. If you customized your existing Space instance before, this is already done. If not, open the space-on-premises-oldversion directory and run:

    docker-compose -p space-on-premises run --entrypoint=cp -v {absolute_path_to_config_folder_on_host}:/home/copy-config init-configs -a /home/init-config/config/. /home/copy-config

    Here {absolute_path_to_config_folder_on_host} is the path to the configuration files destination directory on the host machine.

  5. Enable customization of your new Space instance (the one in the space-on-premises-newversion directory) as described here.

  6. Open the space-on-premises-newversion directory and create configuration files for the new Space version:

    docker-compose -p space-on-premises run --entrypoint=sh init-configs /prepare_default_configs.sh

  7. Copy parameter values from the old version configuration files to the files of the new Space version. Here is the list of files and parameters which values must be copied:

    • space.on-premises.conf:

      • circlet.masterSecret

      • circlet.oauth.accessToken.rsa.public

      • circlet.oauth.accessToken.rsa.private

      • circlet.oauth.message.encoding.key

      • circlet.oauth.twoFactor.encryptionKey

      • circlet.oauth.encryptionKey

      • circlet.oauth.messageSigning.rsa.public

      • circlet.oauth.messageSigning.rsa.private

      • circlet.vcs.secret

      • circlet.vcs.identity.email

      • circlet.vcs.identity.secretKey_base64

      • circlet.webhooks.key

      • circlet.packages.oauth.clientSecret

    • packages.on-premises.conf:

      • circlet.packages.oauth.clientSecret

    • vcs.on-premises.conf:

      • circlet.key

      • vcs.ssh.server.key.rsa.base64

      • Vcs.gpg.public_key.base64

  8. In the new Space version, in the packages.on-premises.conf file, add the circlet.masterSecret parameter. Its value must be the same as in the space.on-premises.conf file.

  9. (This step is relevant only if you initially created your instance with Space On-Premises 2022.1.0-BETA. If you created your instance with Space On-Premises 2022.1.0 or later, skip this step).

    Open the docker-compose.yml file in the space-on-premises-newversion directory. Find the line that defines Java options for the Space service:

    JAVA_OPTS: "-Dconfig.file=/home/space/circlet-server-onprem/config/space.on-premises.conf"
    and add one more option to it:
    JAVA_OPTS: "-Dconfig.file=/home/space/circlet-server-onprem/config/space.on-premises.conf -Dcirclet.organization.domain=jetbrains"

  10. Stop your current instance of Space (old version) by running the following command in the space-on-premises-oldversion directory:

    docker-compose -p space-on-premises down

  11. Start the new Space instance by running the following command in the space-on-premises-newversion directory:

    docker-compose -p space-on-premises up -d

In a Kubernetes installation, PostgreSQL, a MinIO/S3-compatible storage, Elasticsearch, and Redis are configured as external services. You can continue using them in your new Space On-Premises instance.

We will refer to the version of you current Space instance as the old version and to the Space version you're going to upgrade to as the new version.

  1. Get the names of the Space deployment objects:

    kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}

  2. Gracefully shutdown all pods related to the objects from step 1:

    for deployment in $(kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}); do kubectl -n ${KUBE_NAMESPACE} scale deploy ${deployment} --replicas=0 done

  3. Remove all deployment objects related to the old version of Space On-Premises:

    for deployment in $(kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}); do kubectl -n ${KUBE_NAMESPACE} delete deploy ${deployment} done

  4. If you installed your Space On-Premises instance using helm install (see Kubernetes Installation), upgrade the Helm release:

    helm -n ${KUBE_NAMESPACE} upgrade ${SPACE_RELEASE_NAME} ${HELM_REPO}/${CHART_NAME} -f values.yaml

    Here values.yaml is the values file of your current Space On-Premises instance.

    Alternatively, you can generate manifests for your current Space instance and apply them with kubectl:

    helm -n ${KUBE_NAMESPACE} template ${SPACE_RELEASE_NAME} ${HELM_REPO}/${CHART_NAME} -f values.yaml | kubectl -n ${KUBE_NAMESPACE} apply -f-

Last modified: 28 November 2023
Administration of Space On-Premises Renew or Change your Space On-Premises License