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.
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
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
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
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.
- SSL certificates
- Docker VECTR network subnet
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
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
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