How to do upgrade from pre 2.2.0 version for Editor docker container

In iText DITO version 2.2.0 we've changed our containers to be run as non-root user. Because of this there is a potential issue with access to folders and files which were created by containers with previous versions and have mappings to the host machine.

For example, if you had a work directory containing templates created in dito-editor with a version less than 2.2.0, and then upgraded to 2.2.0 which now run as non-root user, the work directory folder can be inaccessible because of lack of permissions.

There are a couple of possible scenarios where this can apply.

Bind mount

In cases when you run your dito-editor container using a bind mount to required folders (as we describe in Start the Editor sections), you need to manually give the following permissions to folders (and all its subfolders and files inside) on the host machine:

• Read permissions
  • application directory (by default this is /opt/dito-editor inside the container, but can be overridden by the DITO_EDITOR_APPLICATION_DIR env variable).
• Read & Write permissions
  • working directory (by default this is /var/opt/dito-editor inside the container, but can be overridden by the DITO_EDITOR_WORK_DIR env variable),
  • config directory (by default this is /etc/opt/dito-editor/shared inside container, but can be overridden by the DITO_EDITOR_CONFIG_DIR env variable).

Permission granting

Permissions can be granted in several ways

1. Give the corresponding permission (w or r) for others (e.g. chmod -R o=r /pathToHostCfgFolder)
2. As we use user and group inside a container with static uid & gid equal to 2000, it's possible to give access via chown (e.g. chown -R 2000:2000 /pathToHostCfgFolder)
3. (Can be used for Windows OS)
   1. Run any container you like (for example the busybox image can be used), using bind mounts to the same host folders as you used when running dito-editor to any folder in the container (e.g. docker run -it -v /var/myWorkDir:/etc/any busybox),
   2. Go to the container shell (docker exec -it <container name> /bin/bash, try sh instead of /bin/bash if it doesn't work),
   3. Give access to folders inside the container to which you've bound a folder from host with a help of one approach from above (e.g. chown -R 2000:2000 /etc/any),
   4. Don't forget to stop & remove your running container.
      

All this can be executed as a one-liner:

docker run -v <path to folder on host>:/etc/any -d -it --name upgradeHelpContainer busybox && docker exec -it upgradeHelpContainer sh -c "chown -R 2000:2000 /etc/any" && docker rm --force upgradeHelpContainer

Don't forget to give permissions to other extra boundfolders or files, if there are any such used.

Named volumes

In cases where  you run dito-editor with named volumes, there are 2 approaches which can be used to give permissions:

Note: this is required only in cases when upgrading from a pre-2.2.0 version is happening with already existing volumes, in other cases there should be no problem creating volumes from scratch.

1. (Manual, system dependent, not applicable to Windows OS)
   1. docker volume inspect <volume name> to find where a volume is on the host machine,
   2. Give permission to a folder on the host machine using one of the approaches from above in Bind mount. Permission granting
2. (System independent)
   1. Run any container you like (for example the busybox image can be used), using the same volumes as you used when running dito-editor to any folder in the container (e.g. docker run -it -v myTestVolume:/etc/any busybox),
   2. Go to the container shell (docker exec -it <container name> /bin/bash, try sh instead of /bin/bash if it doesn't work),
   3. Give access to folders inside the container to which you've bound volumes (e.g. chown -R 2000:2000 /etc/any),
   4. Don't forget to stop & remove your running container.

All this can be executed as a one-liner:
docker run -v <volume name>:/etc/any -d -it --name upgradeHelpContainer busybox && docker exec -it upgradeHelpContainer sh -c "chown -R 2000:2000 /etc/any" && docker rm --force upgradeHelpContainer