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 <installation.html#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 <https://docs.docker.com/engine/reference/commandline/compose_create/>`_
the container and `copy <https://docs.docker.com/engine/reference/commandline/compose_cp/>`_ 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 :doc:`installation guide </getting-started/installation>`.

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 <https://docs.docker.com/engine/reference/commandline/compose_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 <installation.html#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.
