Testing MergeCPF feature

For quite some time InterSystems IRIS supports such thing as Merging CPF. So, with help of this it should be possible to define only desired changes in configuration. And get them applied even with vanilla Docker image. 

And I though it could be useful when used with Dockerfile. Use this way to configure IRIS during docker build instead of using Installer manifest.

Format of the file, is the same as original IRIS.cpf, with addition of one block, with Actions, where you can define a list of actions which will be executed during merging. And this is most interesting part. It can help to create Database file, users, roles, services and so on.

Create a new Database and Namespace, is quite simple, this lines will help with it.

[Actions]
CreateDatabase:Name=TEST,Directory=test
CreateNamespace:Name=TEST,Globals=TEST

In most cases, it uses Config or Security classes, and you may define as many parameters as you need, and for the list of all available parameters you have to look at the corresponding class.

How to call the merge

There is new merge sub-command added to iris command. So, you can do Merge CPF on a running instance.

$ iris merge IRIS merge.cpf

IRIS Merge completed successfully

And it is possible to do this merge during the start of IRIS Docker Image, in this case, the path to merge.cpf have to be in the environment variable ISC_CPF_MERGE_FILE

$ docker run -e ISC_CPF_MERGE_FILE=/dur/merge.cpf containers.intersystems.com/intersystems/iris

Caveats

Unfortunately, I found some issues, which I would like to share here, so, you would know what to expect if you decide to use it

• IRIS Merge completed successfully, it's the only result you will see in the output. And in fact, it does not mean, that anything was even done at all. Some possible situations
  • If you pass, a non-existing path, it's a success
  • It does not accept a relative path, only a full absolute path
  • Type in [Actions], it's case-sensitive, if you have [actions], nothing changes and it's a success, with no errors
  • All good? Yes, if namespace already exists, no changes, and it's a success

    [Actions]
    CreateDatabase:Name=TEST,Directory=test
    CreateNamespace:Name=USER,Globals=TEST

• Error Code
  • Success = 3; In what world success code became 3, I have no idea, when always expected to be 0
  • Error = 7; any non-0 is usually interpreted as an error, so, it's ok at least, in some scenarios it may return it, but difficult to find that scenario
• No output at all, if no errors are found

In the documentation, you may find this example

[Actions]
CreateUser:Name=SQLAdmin,
  PasswordHash="cec6638a357e7586fddfb15c0e7dd5719a1964e774cd37466fb0c49c05,
  323cb89148c887166dd2be61c107710539af2c01b43f07dccc8d030ac2c1a8cf7c5ace4a00d57e3780f,10000,SHA512",
  Roles="%SQL,%DB_USER"
GrantAdminPrivilege:Grantee=SQLAdmin,Namespace=USER,AdminPriv="%DB_OBJECT_DEFINITION,%BUILD_INDEX"

Keep, in mind to remove all new lines in your file, because written this way, it will fail with errors

ERROR #501: Error reading [Actions] section in file /home/irisowner/temp/merge.cpf
ERROR #508: Invalid action 'PasswordHash="cec6638a357e7586fddfb15c0e7dd5719a1964e774cd37466fb0c49c05,' at line 3
ERROR #508: Invalid action '323cb89148c887166dd2be61c107710539af2c01b43f07dccc8d030ac2c1a8cf7c5ace4a00d57e3780f,10000,SHA512",' at line 4
ERROR #508: Invalid action 'Roles="%SQL,%DB_USER"' at line 5
IRIS Merge failed%   

Note: How to get PasswordHash for a desired plain password, is not so easy to find, it is in a different section of the documentation, and only possible with special Docker images just for it, by some unknown reasons this tool you will not find in IRIS Kit.

Conclusion

I know, that I may not test all possible combinations, but even with these results, I see no reasons for recommending using this feature at all. The behavior is very unpredictable, even for development, you would have to manually check if any changes were applied correctly.