Set up an IRIS docker image on a Raspberry Pi 4

Is anyone like me, and felt really jealous that they didn't have enough points to acquire the IRIS-based Raspberry Pi system when it was offered? Do you have a spare Raspberry Pi 4 handy? If so, I'll walk you through setting up Docker and IRIS on your Raspberry Pi so you can have the smallest IRIS computer in town!

Things you'll need:

Raspberry Pi 4 (at least 4G RAM, but I have several with 8G so that's what I used. 2G RAM *might* work, but there might be a lot of swap file activity which would slow down the process considerably)
MicroSD card (at least 16G, but I'd recommend 32G or more)
Power supply capable of running the Pi with USB peripherals
Keyboard & Mouse
Monitor (and required cables to connect)
64-bit Raspberry Pi OS or 64-bit Ubuntu Mate 22.04LTS image
    RasPi Image can be downloaded here: https://downloads.raspberrypi.org/raspios_arm64/images/
    Ubuntu Mate can be downloaded here: https://releases.ubuntu-mate.org/22.04/arm64/
    
    These instructions work for either OS, but for the rest of the tutorial, I used the 64-bit RasPi OS.

Optional, but useful:

Fast USB3 Flash Drive or SDcard reader with high-speed SD (or MicroSD) Card

Step 1: Setup the Raspberry Pi to boot

Image the MicroSD card with the downloaded OS image. Software and instructions can be found here:
    
Basic instructions to set up the Raspberry Pi can be found here:
    https://www.tomshardware.com/how-to/set-up-raspberry-pi
    (Where the tutorial says "32-bit," please be sure to use the 64-bit images listed above.

Step 2: Install Docker

Open a terminal window, and use this command:

sudo apt-get install docker.io

Now, add your main user to the docker group to be able to execute docker commands:

sudo usermod -a -G docker *mainuser*

Step 3 (optional but very useful): Create an 'irisowner' user on the RasPi

This is optional - but if you want to be able to easily mount external USB drives in your IRIS docker container, it helps to have the container userid synchronized with a RasPi OS userid, so let's create a local irisowner user with matching UIDs. Execute these commands:

    sudo addgroup --gid 51773 irisowner
    sudo adduser --shell /bin/bash --uid 51773 --gid 51773 irisowner

Why such an 'odd' user id? It mimics the irisowner userid in the IRIS container, which will make it much easier to mount external media in the docker container. That said, this user won't be able to do much... so let's add enough permissions as the main system user (including being able to run docker images):

    sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,render,netdev,spi,i2c,gpio,lpadmin,docker irisowner

Step 4 (Optional, but very useful): Set up an external USB drive for increased bandwidth

Now that the irisowner user is created, log out of the main user, and log back in as the irisowner user. This will help us set up an external USB drive. Why would we do this? It can be a *lot* faster - the USB3 interface has a lot more available bandwidth than the Pi's internal MicroSD interface you boot from. I'll present a nearly useless benchmark as an example.

Back in the early days of computing, when hard drives first became available for the Tandy Color Computer machines, to rate the different HD systems, there was a benchmark called 'megaread.' It basically timed just how long it took for the CoCo to read a megabyte of info from the drive. Well, I wrote something even more useless but can demonstrate some of the speed gains available to an external USB drive. I dub this code: "Gigawrite:"

W $H,! S P="" F I=1:1:128{S J=$C($R(64)+32),P=P_J} F I=1:1:8 {F J=1:1:1024 F K=1:1:1024 S ^GIG(I,J,K)=P} W $H,!

It just times how long it takes to write a gigabyte of string info into the current namespace/database. I did not play with journaling settings or anything - just default settings on each of the namespaces I built so I admit it's not a great test, but with identical MicroSD cards - one in the boot MicroSD slot, one in an external USB3 reader - here's the difference in times with my Gigawrite utility:

    Internal MicroSD - 269 Seconds
    External USB3 reader: 176 Seconds

If I tinkered with the journalling & other settings, I think I could get a lot more performance from the external USB drives. Food for thought.

On that note, let's go set up that external USB drive. As the irisowner user, insert a USB drive, and verify that it's mounted in the /media/irisowner mount point directory. If it isn't, you may need to reboot the Pi and re-login as the irisowner user.

We'll need to reformat the drive as a Linux EXT2 drive - drive permissions won't work well enough for VFAT or NTFS to work with IRIS.

Insert the USB drive, and then open a terminal session and enter this command:

    sudo fdisk -l

        this command will show you all of the storage devices on the system. Find the USB drive disk name (it's usually last in the string and for this example, it's /dev/sdb, but it may be different on your system).

    sudo fdisk /dev/sdb

        If this returns an error, the USB drive may not be mounted as /dev/sdb. You may need to find where the Raspberry Pi mounted the device and use that instead in the command.
        Press 'd' to delete the current partition.
            If there's only one partition, it will automatically delete it with no extra input. If there are multiple partitions on the drive, you may need to use the 'd' command more than once.
        Press 'n' to create a new partition.
            It will ask you first for a primary or extended partition. Choose 'p' for primary.
            It will also ask you for partition numbers & sector start and end. Just hit {Enter} to accept the defaults.
        Press 'w' to write the new partition table to disk, and the fdisk command will automatically exit.

Next, we need to create a new ext2 filesystem on the disk; use this command:

    sudo mkfs.ext2 -L ExtIris /dev/sdb1

        This may take a little bit of time, depending on the size & speed of the drive.

When the mkfs command completes, eject the drive and re-insert it - you should now see a drive mounted in /media/irisowner/ExtIris. Unfortunately, as we did all the configuration work as root (via the sudo command) we need to change the permissions on that directory to irisowner so we have write permissions. Run this command:

    sudo chown -R irisowner:irisowner /media/irisowner/ExtIris

If you wanted to use the drive for more than just IRIS data, let's create a couple subdirectories:

    mkdir /media/irisowner/ExtIris/IrisData
    mkdir /media/irisowner/ExtIris/IrisData/db1
    mkdir /media/irisowner/ExtIris/IrisData/db2

Step 5: Create the IRIS docker image by running this command:

Depending on if you followed Steps 3 & 4 above will depend on which command you'll run to build the docker image. If you did *not* do 3 & 4, run this command:

    docker run -d --name iris --publish 1972:1972 --publish 52773:52773 intersystemsdc/iris-community

If you *did* set up an external USB drive and want to access that space in the IRIS docker image, run this command:

    docker run -d --name iris --mount type=bind,source=/media/irisowner/ExtIris/IrisData,target=/media/irisowner,bind-propagation=rslave --publish 1972:1972 --publish 52773:52773 intersystemsdc/iris-community

Assuming that doesn't error out (say, no access to the Internet or somesuch) you should have an IRIS container built with the ability to access external USB data! But... to be sure... let's go do some testing!

Step 6: Let's log into IRIS!

You'll need to know the IP address of the active network connection. With that, go to the home page of the IRIS Management Portal:

    http://xxx.xxx.xxx.xxx:52773/csp/sys/UtilHome.csp
        [[ Replace the xxx's with the IP address of the system. ]]
    
    Log in with the _system userid & default password. It'll ask you to change the password for the user, please do so.

You should be in! Go in and play around...

Step 7 (Optional, but educational!): Make an external USB IRIS database & namespace!

Assuming you didn't skip steps 3 & 4 above, your external USB drive is visible to the IRIS docker and you've successfully logged into the System Management Portal, go to:

    System Administration » Configuration » System Configuration » Local Databases.

Click on "Create a new Database" and in the name, type in DB1.
For the directory, traverse back to the root directory, then navigate to /media/irisowner/db1, click Next, then click Finish.

You should now see the DB1 database; let's go create a namespace for it. Go to:

    System Administration » Configuration » System Configuration » Namespaces

and click "Create New Namespace"
    
    Type in 'DB1' for the name (without quotes) and in the dropdowns for Database for Globals & Database for Routines, select the DB1 database, check the "Enable namespace for interoperability productions" box and click Save.

[[ If you want, you can repeat Step 5 with the DB2 directory, but isn't necessary. ]]

Now... technically we're done! You can go play with productions, configurations, whatever. If you have IRIS 2022.x.x installed on a windows machine & have access to Studio, you can even use that to write ObjectScript/M code if you add the IP to the "Remote System Access" menu of the system tray. I can confirm that HealthShare 2017 will not connect remotely to your new Docker image - it's just "too old" to communicate with the newer IRIS.

But... if you're like me and you *like* Terminal sessions? If you asked yourself:

Self! How do I get a standard terminal session into IRIS?

Step 8 (optional): Interact directly with the IRIS Docker Container.

To start a IRIS terminal session in the IRIS docker container, you'll have to do this on the Raspberry Pi at a bash prompt - or - SSH into the Pi remotely from another machine so you have a bash prompt there. Then, enter this command:

    docker exec -it iris irissession IRIS

It should pop you directly into the USER> prompt of the IRIS session. If you did create the USB-stored database(s), you can type this:

    ZN "DB1"

and you should see the DB1> prompt.

Now... what if you wanted to interact not with IRIS, but with the docker container directly? Use this command:

    docker exec -it iris bash

There, you can do all the things a 'normal user' could do in the instance. But.. the normal user really can't do a heck of a lot, and the docker image doesn't have the 'sudo' command to elevate user privileges to do things like create new users, download and install updates, things like that. What's a poor fella to do? Exit out of that, and issue this command:

    docker exec -it -u 0 iris bash

Now you have root user access to the container. Be careful! You may now have the power to do great things... but you also have the power to break things spectacularly!

Footnote: Hopefully I've inspired others that have access to Raspberry Pi computers to go tinker with IRIS on these tiny but powerful little systems.