VECTR 5.1 - 5.4 to 5.5 Migration

VECTR 5.5 is a major release that simplifies installation, improves maintainability, and upgrades third-party software. This guide is written to be a step by step process for those upgrading a standard VECTR deployment on Ubuntu/CentOS.

Migration Video Guide

Preparation

  • The existing VECTR instance should still be present on the host and in a working state

  • You will need read/write access to VECTR configuration files and run environment as well as root level access for Docker(in most cases)

  • GitHub/Docker Hub network access to download 5.5 release package and images

  • It’s highly recommended that you follow Docker’s post-installation notes for running as a non-root user, this will not be covered here: https://docs.docker.com/install/linux/linux-postinstall/

  • Decide on a new location for VECTR 5.5 (referenced here as ~/new_vectr_location) The full recommended path would be /opt/vectr_5_5

  • Depending on your environment you may need to add sudo to your commands for permissions reasons. It has been added to the commands where it will most likely be needed, but this may cause issues in your environment

Upgrade Process

0. Create a new VECTR directory and download the release package

wget https://github.com/SecurityRiskAdvisors/VECTR/releases/download/ce-5.5.6/sra-vectr-runtime-5.5.6-ce.zip -O /srv/vectr

unzip sra-vectr-runtime-5.5.6-ce.zip

1. Find your previous .env file

If familiar with this file, continue to step 2. Otherwise, this is a file created by the previous VECTR installer. If you did not use a .env file, you will need to reference various other VECTR configuration files for config values(Uncommon). This file will often be found in a location like ~/vectr-staging/sravectr.env

If having difficulty finding this file try a find command like this

sudo find / -name <vectr-install-name>.env

If you are unsure of the install name, start by running a docker command to see your container names

sudo docker ps -a

From this we can see from the container names the install was named(for example) internalvectr, so we would run

sudo find / -name internalvectr.env

This should return the location of the .env file needed

2. Identify VECTR installation and data directories

more <vectr-install-name>.env

You need two directories as follows:

  • VECTR_DEPLOY_DIR This directory tells us where to run the docker compose from to stop the current containers
  • VECTR_DATA_DIR This directory is where the data inside VECTR is stored

Note only for manual installations (no .env file): If this file is not present due to a manual installation, this information can be gathered from the docker-compose.yml and devSsl.yml files used by VECTR. The shared volume information in the docker compose and devSsl files will include the correct paths for application and data directory. If the defaults were used and no .env exists, those locations may be /opt/vectr for the application installation directory and /var/data/sandbox1 for the data directory.

3. Move to your VECTR_DEPLOY_DIR and run a docker-compose down

This will stop your current containers and remove them. Since our data is stored on the host, no data loss will occur.

cd <VECTR_DEPLOY_DIR>
docker-compose -f docker-compose.yml -f devSsl.yml -p <vectr-instance-name> down

Note: < vectr-instance-name > is the same as earlier when trying to find your .env file

4. Back up VECTR Data

It is recommended to Tar up your VECTR data directory and move the tarball to a safe archive location

tar cvfz vectr_5_5_upgrade_backup.tar.gz <VECTR_DATA_DIR>

5. Create a temporary data directory

Create a temporary data directory for use by the MongoDB version upgrade tool, copy in existing VECTR data files, and create a location for upgraded VECTR data

mkdir -p ~/new_vectr_location/tempdata
mkdir -p ~/new_vectr_location/upgradeddata
sudo cp -r <VECTR_DATA_DIR> ~/new_vectr_location/tempdata/

6. Run the MongoDB Upgrade Tool

The next step is to run our custom migration container to upgrade the VECTR data for use with the new Mongo DB versions. We will need to run a command that gives docker all the appropriate directories. Please note the directories used here with ~/new_vectr_location. These are the directories we created in the previous step, fill in those values you used.

Run a command like the following:

docker run -v ~/new_vectr_location/tempdata/:/var/tmp/userdata/ -v ~/new_vectr_location/upgradeddata/:/var/tmp/outputdata/ securityriskadvisors/sra-mongodb-upgradetool:0.0.1-SNAPSHOT`

To break this down, we’re mounting a volume with the current VECTR data that we copied to tempdata as the folder /var/tmp/userdata on the mongodb-upgradetool container file system. Then we’re mounting a new location for the upgraded data to /var/tmp/outputdata/ on the upgradetool container file system. The name of the docker image for the upgrade tool is securityriskadvisors/sra-mongodb-upgradetool

On successful completion you should see a new 4.2 directory with mongodump files in it under ~/new_vectr_location/upgradeddata/ or whatever path you mounted to correspond with the outputdata directory.

7. Copy the upgrade data

Now we need to place the upgrade data in our new VECTR location user/mongo directory

mkdir -p  ~/new_vectr_location/user/mongo/
cp -r ~/new_vectr_location/upgradeddata/4.2/* ~/new_vectr_location/user/mongo/

Note, this command is using example directories. You need to fill in whatever directories you created earlier.

8. Reference your previous VECTR installation

Again reference your previous .env file, configuration files and installation notes. If you used the installer previously the .env should have most if not all of the information required. The items you will need from the .env depend on your configuration, but examples are.

  • Hostname
  • Port
  • SSL certificates
  • Docker VECTR network subnet
  • VECTR_DATA_KEY

9. Setup the new .env file

For setting up the new .env file you will need to use some form of text editor. For example from your new_vectr_location run

nano .env

In this case, we’ll compare the old vectr-install-name.env file and the new file at ~/new_vectr_location/.env and modify ~/new_vectr_location/.env with the desired values

Note that hostname, port, data key should match your old .env file. MONGO_INITDB_ROOT_PASSWORD and CAS_ENCRYPT_MONGO_KEY should be unique strings that you generate and put in your ~/new_vectr_location/.env file

See this photo for an example

CompareEnv

Note if you need to configure an SSL certificate and will not be using the auto-generated see SSL Configuration

10. Startup your new 5.5 VECTR instance

docker-compose up