JetBrains Space Help

Migrate from Earlier Versions

If you used Space On-Premises 2022.1 Beta, it is possible to transfer all your data to a new 2023.1 installation.

What you should take into account:

  • Space On-Premises supports only forward updates – it's not possible to downgrade to previous versions.

  • The Beta license is valid only till January 31, 2023. After that date, you won't be able to use your Space On-Premises instance though migration will still be possible.

  • The Space On-Premises Beta version provides the feature set equivalent to the Organization plan of the release version. Nevertheless, it's possible to migrate Space On-Premises Beta to the Free plan which has fewer features available. If your Beta installation has entities provided by the Organization plan, these entities will be migrated, but it will not be possible to create new similar entities.

  • Migration from Beta to 2023.1 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.0:

    export SPACE_RELEASE_NAME="2023.1.0" 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 January 2023
Administration of Space On-Premises FAQ and Troubleshooting