Migrating from JAR to Docker

If you want to move to a Docker based installation, and you’ve already been running CodeScene for a while with the standalone JAR, you probably want to migrate your data to the new installation. This process involves:

  1. Setting up the database in docker

  2. Running a migration script to rewrite old paths in the database

  3. Generating new SSH keys (if needed)

Step 1 differs depending on if you are running the built-in embedded H2 database or MySQL. Both processes are described below.

Note: We do not support migrating projects specifying a git repo from the local filesystem. Such projects will be removed in the migration.

General information about getting started with Docker can be found at Run CodeScene Application inside a Docker container .

Step 1a: Embedded H2 database

Running using a built-in embedded H2 database is the default setting in CodeScene. A simple docker-compose.yml without any variables will do the trick:

version: '3'
services:
  codescene:
    image: codescene/codescene:latest
    ports:
      - 3003:3003
    volumes:
      - codescene:/codescene

volumes:
  codescene:

Before starting CodeScene for the first time, create the container and copy the old database file into the docker volume:

$ docker compose create
$ docker compose cp <PATH TO OLD DB> codescene:/codescene/codescene.mv.db
$ docker compose cp <PATH TO OLD DB>.before-upgrade codescene:/codescene/codescene.mv.db.before-upgrade

The path to the old database file is either resources/caacs_enterprise.db.mv.db or set by the CODESCENE_DB_PATH environment variable. During time the H2 database was migrated to version 2, you need to copy also the file ending with .before-upgrade if exists.

Step 1b: MySQL database

We recommend making a copy of the old database before proceeding, because the migration script in the next step will alter the data. By making a copy you can easily go back to the JAR installation should you need to.

The docker container needs the right environment variables to connect to an external database. The variables are the same as when running the standalone JAR described in the installation guide.

Here is an example using docker compose:

version: '3'
services:
  codescene:
    image: codescene/codescene:latest
    ports:
      - 3003:3003
    volumes:
      - codescene:/codescene
    environment:
      - CODESCENE_DB_ENGINE=mysql
      - CODESCENE_DB_HOST=<external host>
      - CODESCENE_DB_NAME=<db name>
      - CODESCENE_DB_USER=<user>
      - CODESCENE_DB_PASSWORD=<password>

volumes:
  codescene:

Step 2: Running migration script

Because the old database contains paths to directories on the local filesystem where analysis results and cloned repos are stored, these paths need to be rewritten for the Docker installation.

Before starting CodeScene in Docker for the first time, run the docker-migration.sh script that is built into the docker image. With docker compose, we can first run the check command to check that we have access to the database, and which projects that will be migrated:

$ docker compose run --entrypoint "docker-migration.sh check" codescene

After that, we can run the migration:

$ docker compose run --entrypoint "docker-migration.sh run" codescene

This script rewrites database paths for the Docker installation. It does not physically copy existing analysis result folders.

Optional: Move existing analysis result folders

Docker installations normally store analysis results under the configured Docker volume, and most Docker users do not need to run a separate result-folder migration. If you have an exceptional setup where existing analysis result folders must be physically moved into CODESCENE_ANALYSIS_RESULTS_ROOT, run CodeScene once with the result-folder migration startup option.

Mount the old result root into the container, make sure CODESCENE_ANALYSIS_RESULTS_ROOT points at the target root, and override the entrypoint for the migration run:

$ docker compose run --entrypoint "java -jar /opt/codescene/codescene-enterprise-edition.standalone.jar --migrate-results-from=/old-results" codescene

The /old-results path in the example must be the path inside the container. Because this bypasses the default container entrypoint, make sure the target root exists and that the process has read, write, and delete permissions for the mounted result folders. The migration moves each affected project result folder to CODESCENE_ANALYSIS_RESULTS_ROOT and updates the stored database paths. When the old and new roots are on different file systems, CodeScene falls back to copying the project folder and deleting the old folder after the database update succeeds. If a target project folder already exists, CodeScene moves children from the old project folder into the existing target folder instead. If the folders have already been moved manually, CodeScene can still update the database paths when it finds the target project folders. Re-running the migration after a successful run is a safe no-op. Do this during a maintenance window and keep a backup of the database and result folders before running it.

Step 3: (Optional) SSH keys

Generate SSH keys for the new installation according to the documentation at Git repository access .

Step 4: (Optional) Mount Repositories

If you’ll be analyzing local Git repositories, you need to mount them into your Docker container:

Here is an example using docker compose:

version: '3'
services:
  codescene:
    image: codescene/codescene:latest
    ports:
      - 3003:3003
    volumes:
      - codescene:/codescene
      - ../repos/our-product:/repos/our-product

volumes:
  codescene:

Running CodeScene

At this point CodeScene should be ready to run. With docker compose we can start it like this:

$ docker compose up -d

Please note that you will need to re-run an analysis for your projects to be able to access the analysis dashboards. Also note that CodeScene will start to re-clone git repositories when starting up again so manual requests for analyses may be queued up for a while.