Skip to content
GitHub

Migrating to Non-root Containers

The purpose of this migration is to run VECTR containers in non-root mode. This migration will set up VECTR containers to run as non-root as well as update the persistence mechanism from bind-mount to named volumes. With named volumes, the Docker service manages the volume and provides additional capabilities for managing your persistence layer. Click here for more information about volumes.

Pre-Migration Prep

Backup VECTR data

If you currently do not have a backup solution for your VECTR data (Mongodb), it is highly recommended that you perform the steps outlined below to create a backup of your data.

Note

Replace <container> with the container name or ID of the Mongodb container. Use docker ps to view this information.

  1. Use mongodump to create a backup archive of VECTR data: 

    [sudo] docker exec -it <container> mongodump --username admin --password --authenticationDatabase admin --archive="vectr_data_archive"

    1. Enter your Mongodb admin password at the prompt

  2. Copy the archive to a safe backup location. For this example, we’re just going to copy the data archive to the home directory:

    mkdir ~/vectr_backup
[sudo] docker cp <container>:/vectr_data_archive ~/vectr_backup/vectr_data_archive

Backup VECTR files

Back up all VECTR files that are on your host.

Note

The following commands assume that you are in the directory of your VECTR installation.

  1. Stop VECTR containers 

    [sudo] docker-compose stop

  2. Archive and compress the files for easy handling 

    [sudo] tar -czf vectr_files.tar.gz logs/ redisData/ resources/ user/

  3. Copy the archive to a safe backup location. For this example, we’re just going to copy the archive to the same location as where we placed the Mongo backup: 

    cp vectr_files.tar.gz ~/vectr_backup/

Docker Engine and Docker Compose Compatibility

With the migration to Docker volumes, VECTR now uses the Docker Compose file format version 3.4. With this change, the following are required:

  • Docker Engine version must be 17.09.0 or greater
  • Docker Compose version must be 1.17.0 or greater

Attention

If you are currently running Docker Engine or Docker Compose that are older than the versions specified above, you must update them before continuing.

Perform Migration

1. Configure permissions for VECTR directories

Note

The example commands assume a Ubuntu / Debian host. If you are on a different Linux distro, use the equivalent commands (if different) for your distro.

  1. Create a vectr group 

    sudo addgroup --gid 10001 vectr

  2. This step is optional and will enable your user account to view files generated by the containers, and not have to change the permissions of directories being bind-mounted.

    Add the Linux user account that you use to manage VECTR deployment to the vectr group and modify the default permission umask.

    1. Add user to the vectr group 

      sudo usermod -aG vectr <username>

    2. Update the permission umask. Change the UMASK value from 022 to 002. This will effectively give read/write permission to the group when you create new files and directories. 

      sudo vi /etc/login.defs

# Change the UMASK value from 022 to 002

    3. Reboot 
      sudo shutdown -r now

  3. Change the group for VECTR associated directories 

    sudo chgrp -R vectr /opt/vectr/logs /opt/vectr/redisData /opt/vectr/resources /opt/vectr/user

  4. Add read and write permission for the group for VECTR associated directories 

    sudo chmod -R g+rw /opt/vectr/logs /opt/vectr/redisData /opt/vectr/resources /opt/vectr/user

Podman Support

If you are using Podman, run the following command to set the permissions for the user bind mount:

podman unshare chown -R 10001:10001 /opt/vect/user

2. Download VECTR non-root migration Docker Compose file

Download here or copy the VECTR non-root migration Docker Compose file (non-root-migration.yml) to your VECTR installation directory.

Attention

The bind mounts assume the default paths. If you have changed the path to VECTR mounts, you must reflect those changes in the non-root-migration.yml file as well before continuing.

For example: In your docker-compose.yml file, if you changed the default resources mount from ./resources:/opt/vectr/resources to /ext/resources:/opt/vectr/resources, then you must also update the resources mount in non-root-migration.yml to be /ext/resources:/migration/from/opt/vectr/resources:ro

3. Run the migration container

This migration will copy VECTR data from the old bind mounts into newly created named volumes.

[sudo] docker-compose -f non-root-migration.yml up

Wait for the container to run and exit. You should see something like this as the last output from the run:

Migration Status

4. Backup your current docker-compose.yml file

mv docker-compose.yml docker-compose-old.yml

5. Download the latest VECTR Docker Compose file and place it in your VECTR installation directory

Download the latest VECTR release from Github.

6. Start the containers

[sudo] docker-compose -f docker-compose.yml up -d

7. Wait for the containers to boot up and VECTR to load

8. Verify that everything is working as expected

At this point, the VECTR containers will be running as non-root. You should verify that everything is working as expected.

Clean Up

Note

These steps are optional.

After you have verified that the non-root version of VECTR is functioning as expected, you can clean up the old VECTR containers and the migration container.

You can selectively remove the containers using the associated Docker Compose file, however, the easiest way to remove "orphaned" containers is to use the --remove-orphans flag.

  1. CD to your VECTR installation directory 

    cd /opt/vectr

  2. Stop VECTR containers 

    [sudo] docker-compose stop

  3. Start VECTR containers again using the --remove-orphans flag 

    [sudo] docker-compose -f docker-compose.yml up --remove-orphans -d

  4. You can also optionally remove any old bind mount directories. Before you continue with this step, make sure that you have a backup of all VECTR associated files 

    [sudo] rm -r logs/ redisData/ resources/

Getting Data Out Of A Container

With VECTR using named volumes for its persistent storage, you can no longer access VECTR generated files from the host's filesystem. Instead, you will need to use the docker cp command to get files out of a running container.

For example, to retrieve the auto-generated CA certificate (if you did not supply your own), run the following:

docker cp <container>:/opt/vectr/resources/certs/ca/vectrRootCA.pem ./vectrRootCA.pem

Replace <container> with the container name or ID of the Mongodb container. Use docker ps to view this information.