Space On-Premises 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.1.1:

    export SPACE_RELEASE_NAME="2023.1.1" 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

  1. Back up Space data. Here you can find the primary considerations of what you should back up.

  2. Space On-Premises Beta could create excessive index data in Elasticsearch. Before starting the migration, delete the redundant indices.

    1. Run bash on the Elasticsearch host. For the Docker Compose installation:

      docker-compose -p space-on-premises run -it elasticsearch bash

    2. List all Elasticsearch indices. For the Docker Compose installation:

      curl elasticsearch:9200/_cat/indices/space-automation.tracing*

    3. If there are more than 10 indices that match the space-automation.tracing* pattern, delete them. For the Docker Compose installation:

      curl -XDELETE elasticsearch:9200/space-automation.tracing*

How to migrate

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

The instructions imply that your Space On-Premises Beta instance is installed to the space-on-premises-beta directory. The new Space On-Premises instance will be installed to the space-on-premises directory.

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

    mkdir -p space-on-premises && 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.1.1:

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

  3. 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-beta 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.

  4. Open the space-on-premises 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

  5. Copy parameter values from the Beta 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.sshServerKeyRSABase64

      • Vcs.gpg.public_key.base64

  6. Open the docker-compose.yml file in the space-on-premises directory.

  7. 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"

  8. Now, you should make your new Space version (the one in the space-on-premises directory) use the created configuration files. To do this, enable customization of the Space service as described here.

  9. Stop the Beta instance of Space by running the following command in the space-on-premises-beta directory:

    docker-compose -p space-on-premises down

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

    docker-compose -p space-on-premises up

  11. Activate your new instance of Space On-Premises.

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.

  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 Beta 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-

  5. Activate your new instance of Space On-Premises.

Last modified: 17 February 2023
Administration of Space On-Premises FAQ and Troubleshooting