Setting up IPM development containers

[isc-bsherman]

I followed the instructions on the "Contributing" page and when I ran the command to set up the containers, I encountered a port error:

Error response from daemon: ports are not available: exposing port TCP 0.0.0.0:52775 -> 127.0.0.1:0: listen tcp 0.0.0.0:52775: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

Note that my other container for HS work is not using this port and I am unaware of what else might be.

Furthermore, could we get some guidance on what the various containers are intended to be used for?

[isc-dchui]

@isc-bsherman Are you using Docker on Windows? This may be an issue with WinNat. Try this in a terminal running as administrator

net stop winnat
docker-compose up -d [<etc.>]
net start winnat

For the containers, there are some details here but the short of it is that the iris container is where IPM development should happen, the registry container runs an instance of the zpm-registry, the oras container runs a zot OCI registry, and sandbox is an empty IRIS container.

[isc-bsherman]

@isc-dchui thanks, the net start and net stop worked. Thank you!

Could you update the Contributing page to include this tip?

I still don't know how to proceed with the 4 containers or what to use them for. I don't know what zpm-registry is, and doing a search here in the repo did not answer the question, it just produced places where it's mentioned as if the reader already knows what it is.

I've never heard of zot or OCI (and looking them up left me more confused).

Am I supposed to use the registry container to test my changes? Or is that what the sandbox is for? How do I get my code onto those servers? Via Github? By publishing and then pulling back down on the other server? Or what?

[isc-dchui]

@isc-bsherman I'm glad that worked! My apologies for not being clearer on what each of these terms mean. You're right that we should definitely define these in an easy to find location.

zpm-registry is the InterSystems Community home-cooked registry that lives here. This is the back end to pm.community.intersystems.com.

OCI registries are the industry standard type of registry, e.g. Artifactory, and zot is a small open source implementation that we've included in a container here for easier testing.

To develop in these containers, you'll want to connect VS Code to the iris container, which is by default exposed to 52774. You can make changes to IPM here and as long as you have the "Compile on Save" VS Code option checked, your saved changes will be automatically compiled and update the code running on that instance. To access the container, use this terminal command docker exec -it ipm-iris-1 bash. This gets you inside the container, where you can then run iris session iris to get inside the IRIS shell and zpm to get inside the IPM shell.

Testing your change depends on what kind of change you're making, but can often involve installing modules or otherwise interacting with registries, which is where the registry and oras containers come into play.

In order to get the IPM instance in the iris container to talk with the registry repo, run this in the zpm shell:
repo -r -name local -url http://registry:52773/registry -username admin -password SYS

In order to get the IPM instance to talk with the oras repo, run this in the zpm shell:
repo -o -name zot -url http://oras:5000/

You can see the contents of the zot registry by going to http://localhost:5001/home in your regular browser.

I hope this helps! Let me know if you have any other questions or areas you'd like me to clarify!

[isc-bsherman]

"you'll want to connect VS Code to the iris container, which is by default exposed to 52774." - how? I've tried adding it to my VS Code sever list and get errors. I've tried to add it to my web gateway container and get no response when I try to open Management Portal. When I look for documentation in Confluence I get links to test plans and other irrelevancies.

[isc-kiyer]

To change the ports used for any of the 4 containers spun up, edit them in the docker-compose file. The defaults used are 52774, 52775, 52776 and 5001. Only the ipm-iris-1 (default of 52774) is what is used for IPM dev (as noted in the contributing guide, this is the one the IPM source code is loaded into in the USER ns). So if you are hitting port conflicts with any of those, update them in the docker compose file and then run docker compose up -d --build again.

[isc-dchui]

@isc-bsherman If the 52774 port is not used by anything else (such as an existing IRIS instance), or you changed it to a different unused port and subsequently rebuilt the docker containers, opening the main "ipm" directory in VS Code should automatically connect it to the instance. You'll be able to check/toggle the connection in the very bottom row of icons on the left side, where it will say "ObjectScript ⊗" if the connection is not enabled, or "docker:iris:52774[USER]" if it is.

[isc-bsherman]

@isc-dchui Thanks, I was able to do this by clicking the "Open in VS Code" option in the ellipsis menu in Docker Desktop. I wasn't able to find "the main ipm directory" from the VS Code side.