Skip to content
GitHub

Non-Root migration FAQ

Attention

This is to help users understand design decisions made when creating the image. This doc is not making recommendations for host configuration, it's merely informational.

User Identifier / Group Identifier

What is the importance of UID / GID?

These are numbers that the Linux kernel uses to determine access to system resources. Because containers and the host share the same kernel, they share the same UID/GID space. If we want a container to be able to access resources on the host, it needs proper permissions.

What UID / GID are VECTR containers using?

By default we are setting a user of 'vectr' in the container with a UID/GID of 10001/10001. ContainerPermissions

How does this affect my environment?

VECTR will attempt to write files to the host whenever there is a bind-mount from your host into a container. Here is an example in the docker-compose.yml: BindMountVsNamedVolume

Attention

If the directory "./resources" does not exist prior to running the "docker-compose up" command, docker will create the directory for you, owned by root. OwnedByRoot

The container will not have permissions to write to that directory, and the logs will have errors ResourceErrors

Make sure that the directory being bind mounted is created prior to running "docker-compose up", and has proper permissions.

Note

In this example, we have a group 'vectr' that has a gid of 10001 Id

Can I change the default container username and uid/gid?

Not currently. We will need to deliver the Dockerfile so users can override some of the commands run to create the image. This is being investigated.

Why are we creating a 'vectr' group?

While this is not Linux Admin advice, the easiest way to ensure you have the correct permissions when creating the directory that your bind-mounts will use is to create a group that will give gid 10001 write permissions by default, then add yourself to that group.

Note

The below instruction are for Debian based distros.

  1. Create a 'vectr' group: 

    sudo addgroup --gid 10001 vectr

  2. Add your user to the group: 

    sudo usermod -aG vectr <username>

  3. Change your user’s default group to vectr: 
    sudo usermod -g vectr <username>
  4. Change the default UMASK for newly created directories to include write permissions for the groups: 
    #change UMASK from 022 to 002:
vi /etc/login.defs
    Umask
  5. Reboot to take effect
  6. Recreating the resource dir will have write permissions by the vectr group with 10001: ProperPermissions

Upgrading Gotchas

Attention

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

I changed the vectr-tomcat image to 8.0.0 in the docker-compose.yml. I'm getting errors in the logs when doing 'docker-compose up'. What do I do?

This means you probably skipped a migration step, or your docker-compose executable version is not upgraded, or your 'version' in your docker-compse.yml is < 3.4.

  1. Revert your docker-compose.yml file to the version you were previously on
  2. Follow full procedure for successful upgrade

I changed the vectr-tomcat image to 8.0.0 in the docker-compose.yml and confirmed the versions of docker-compose executable and docker-compose.yml versions are correct. All of my data has disappeared. How do I proceed?

This probably means that the docker-compose.yml is using a named volume, but all your data is still in the old bind-mount. There is a migration step that copies your data from your old bind-mount to the newly created named volume.

  1. Revert your docker-compose.yml file to the version you were previously on
  2. Follow full procedure for successful upgrade

How can I use Podman on CentOS 8?

We were able to successfully run VECTR using the docker-compose.yml leveraging the podman-compose project on CentOS 8. As of 10/1/2021, the version that is available to pip3 does not support mounts. We had to use a development version to get all the functionality.

Attention

'sudo pip3 install podman-compose' will install the wrong version

Install the development build:

sudo pip3 install https://github.com/containers/podman-compose/archive/devel.tar.gz

Once installed, you can use 'podman-compose up' to bring up the containers. Podman