JetBrains SpaceCode Preview Help

Upgrade from Earlier Versions

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

Minor updates

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

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

  1. Open the SpaceCode 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 2024.3.3:

    export SPACE_RELEASE_NAME="2024.3.3" 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 SpaceCode version, apply the corresponding changes to the new docker-compose.yml.

  4. Restart your SpaceCode 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 SpaceCode On-Premises instance.

Major updates

These updates change the major SpaceCode version, for example, from 2024.1.1 to 2024.2.2, or from 2024.1.3 to 2024.3.0. Such updates bring new features and might require changes in databases and infrastructure configuration. To perform a major update, you should migrate SpaceCode 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 SpaceCode 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 SpaceCode On-Premises instance is installed to the space-on-premises-oldversion directory. The new SpaceCode On-Premises instance will be installed to the space-on-premises-newversion directory.

  1. Create and open an installation directory for the new SpaceCode 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 2024.3.3:

    export SPACE_RELEASE_NAME="2024.3.3" 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 SpaceCode version, apply the corresponding changes to the new docker-compose.yml.

  4. Migration requires editing SpaceCode configuration files, meaning that the files must be copied from a SpaceCode container to the host machine. If you customized your existing SpaceCode 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 SpaceCode 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 SpaceCode 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 SpaceCode 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 SpaceCode 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 SpaceCode On-Premises 2022.1.0-BETA. If you created your instance with SpaceCode 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 SpaceCode 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 SpaceCode (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 SpaceCode 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 SpaceCode On-Premises instance.

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

  1. Get the names of the SpaceCode 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 SpaceCode 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 SpaceCode 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 SpaceCode On-Premises instance.

    Alternatively, you can generate manifests for your current SpaceCode 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: 05 August 2024
Administration of SpaceCode On-Premises Renew your SpaceCode On-Premises License