Migration

Foreword

If you need help, please create an issue on GitHub.

To Docker Compose

Situation

You are using the old virtool.tar.gz installation (not Docker) and want to migrate to Docker Compose.

Overview

The Virtool data directory and MongoDB database need to be made available to the Docker container.

After the migration, the built-in software update system will no longer work.

Data Directory

The data directory refers to the directory configured in Virtool with the --data-path option.

The simplest way to make the data directory available to the Docker container is to use a bind mount. This will map a location on your host machine to a location in the Docker container.

Instead of using a volume, configure a bind mount in docker-compose.yml:

docker-compose.yml

   version: "3.1"
   services:
     mongo:
       image: mongo:4.0
       ports:
         - "27017:27017"
       volumes:
         - mongo:/data/db
     virtool:
       image: ghcr.io/virtool/virtool:4.3.3
       environment:
         VT_DATA_PATH: "/data"
         VT_HOST: "0.0.0.0"
       ports:
         - "9950:9950"
       volumes:
         # Bind mount the data directory from the host machine to the container. It will
         # be located at /data in the container.
         - type: bind
           source: /mnt/virtool_data_on_host
           target: /data
   volumes:
     # MongoDB data is stored in a volume.
     mongo: null

MongoDB

We will deploy MongoDB as a Docker container and copy your existing database to the container.

Ensure MongoDB is configured and running in Docker.

You can double-check MongoDB is running by running docker ps. You should see similar to:

 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                      NAMES
 1a2b3c4d5e6f        mongo:4.0           "docker-entrypoint.s…"   2 hours ago         Up 2 hours

Stop your existing Virtool server. This will prevent any changes being made to your existing MongoDB database while we migrate.
Dump your existing MongoDB database into a file called virtool.dump.

This will not affect the existing database!
```
mongodump --db virtool --archive=virtool.dump
```

Restore the MongoDB database into the new MongoDB Docker container.

docker-compose exec -T mongo sh -c 'mongorestore --archive' < virtool.dump

To a Newer MongoDB Version

MongoDB 3.6.0 or newer is required in Virtool 4.0.0

Virtool will not start if it detects that the configured database does not meet this requirement
Virtool versions prior to 4.0.0 are not compatible with MongoDB 4.0.0

In Docker Compose

Follow these instructions if you have MongoDB running in Docker Compose.

Backup the Database

First, backup your database using the following command (assuming your database is called virtool). This will dump the entire database to a folder that can later be restored if necessary.
```
docker-compose exec -T mongo sh -c 'mongodump -d virtool --archive' > virtool.dump
```

Check Compatibility Version using mongo.

Open a Mongo shell:

mongo

In the shell, check the current featureCompatibilityVersion value:

db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 });

The response should contain the current version compatibility information:

// Nothing needs to be done in this case.
{ "featureCompatibilityVersion" : { "version" : "3.4" }, "ok" : 1 }

// Feature compatibility must be set to 3.4 in this case.
{ "featureCompatibilityVersion" : { "version" : "3.2" }, "ok" : 1 }

Update Compatibility Version

If the version value is not 3.4, the compatibility version need to be updated:
```
db.adminCommand({ setFeatureCompatibilityVersion: "3.4" });
```
The featureCompatibility value should now be set to 3.4. Check using:
```
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 });
```
The response should have the value set to 3.4.
```
{ "featureCompatibilityVersion" : { "version" : "3.4" }, "ok" : 1 }
```
Update Database Software

Install MongoDB 3.6 according to the instructions from MongoDB:
Update Compatibility Version

The featureCompatibilityVersion now needs to be set to 3.6. This process is the same as in step 2 except the value is being set to 3. 6 instead of 3.4.

Open the Mongo shell and set the compatibility version:
```
db.adminCommand({ setFeatureCompatibilityVersion: "3.6" });
```
The featureCompatibility value should now be set to 3.6. Check using:
```
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 });
```
The response should show the version value set to 3.6.
```
{ "featureCompatibilityVersion" : { "version" : "3.6" }, "ok" : 1 }
```

On Host

Follow these instructions if you have MongoDB running directly on the your machine. Not in a Docker container.

Backup the Database

First, backup your database using the following command (assuming your database is called virtool). This will dump the entire database to a folder that can later be restored if necessary.
```
mongodump -d virtool
```

Check Compatibility Version