Skip to main content

Deploy and Explore InterSystems IRIS

Want to see what InterSystems IRIS® data platform can do? There are several fast and easy ways.

This document explains how to deploy InterSystems IRIS Community Edition or InterSystems IRIS BYOL, and describes some ways in which you can explore your InterSystems IRIS instance.

Note:

The InterSystems IRIS container provided on a Community Edition cloud node is always named iris; for this reason, all examples in this document assume the container involved is named iris.

Deploy InterSystems IRIS Community Edition on Your Own System

You can deploy a containerized instance of InterSystems IRIS Community Edition on your own public cloud, private cloud, or hardware system from the Community Edition image, using the following steps:

  1. Ensure that Docker is installed on your system. (Docker images from InterSystems comply with the OCI support specification, and are supported on Docker Enterprise Edition and Community Edition, version 18.03 and later. Only Docker EE is supported for production environments.)

  2. Use the docker pull command to download the image from the InterSystems Container Registry (ICR), described in Using the InterSystems Container Registry, for example:

    $ docker pull containers.intersystems.com/intersystems/iris-community:2020.2.0.211.0
    5c939e3a4d10: Pull complete
    c63719cdbe7a: Pull complete
    19a861ea6baf: Pull complete
    651c9d2d6c4f: Pull complete
    $ docker images
    REPOSITORY                  TAG            IMAGE ID     CREATED    SIZE
    intersystems/iris-community 2020.2.0.211.0 15627fb5cb76 3 days ago 1.33GB
    
    Copy code to clipboard

    You can also download Community Edition from the Docker Store by replacing containers.intersystems.com with store in the previous example.

  3. Load the Docker Store’s InterSystems IRIS data platform page in your browser. Under Community Edition in the upper right-hand corner, click the Setup Instructions button to display brief instructions for running the container.

  4. At your system’s shell prompt, follow the instructions displayed. Make a note of the host ports to which you publish the InterSystems IRIS instance’s superserver and web server ports. For example, the instructions contain the following options:

    --publish 52773:52773
    --publish 1972:1972
    Copy code to clipboard

    These options publish the instance’s superserver port (1972) and web server port (52773) as the same ports on the host, so that you can interact with InterSystems IRIS from outside the container using the default ports.

    Note:

    If the container fails to start, with an error message indicating that your system has too many cores for the Community Edition license, first remove the stopped container with the command docker rm my-iris, then insert the option --cpuset-cpus=0-7 after the --name option in the docker run command. This restricts the container to using eight cores, which is the Community Edition limit.

  5. Execute the docker ps -a command to see the status of the container, which is called iris, and confirm that it is running.

That’s it! You are the proud owner of an InterSystems IRIS Community Edition instance running in a container. The instance comes with a free built-in license that expires a year after the product version’s release date, as well as a production-enabled USER namespace (there are also some limitations).

Once the container is running, you can continue with the instructions in Explore Your InterSystems IRIS Instance.

Note:

The provided setup instructions are valid for most Docker environments; if you encounter any problems, see Running InterSystems IRIS Containers and Additional Docker/InterSystems IRIS Considerations in Running InterSystems Products in Containers. For information specific to Docker for Windows, see Using InterSystems IRIS Containers with Docker for Windows on InterSystems Developer Community.

Deploy InterSystems IRIS Community Edition on a Cloud Node

To deploy Community Edition on a public cloud node, do the following:

  1. Log into your Google Public Cloud, Amazon Web Services, or Microsoft Azure account. If neither you nor your employer have one yet, you can go to the GCP, AWS, or Azure portal page to quickly create a free account. Select or create a project (GCP), an IAM user and credentials (AWS), or a resource group (Azure).

  2. You can find the InterSystems IRIS Community Edition page for your cloud provider in two ways:

    • Go to the Get InterSystems IRIS Today! page and select the appropriate TRY IT button. Get InterSystems IRIS Today! also includes links to short video tutorials on getting started with a cloud node.

    • Go to the cloud provider’s marketplace page and search for InterSystems IRIS.

  3. On the listing page, click Launch (GCP), Continue to Subscribe (AWS), or Create (Azure), follow the prompts and fill in the required fields, then click Deploy when ready.

    Note:

    On Azure, to simplify making SSH connections to the cloud node, find the Administrator account section at the bottom of the Basics tab on the Create a virtual machine page, select Password for Aunthentication type, and enter a username and password.

    On AWS, for a more streamlined experience, choose Launch through EC2 at the first prompt on the Launch this software page. (If you continue on the website, at the Security Group Settings drop-down, be sure to select Create New Based On Seller Settings.)

That’s it! You are the proud owner of an InterSystems IRIS Community Edition instance on a cloud node. The instance comes with a free built-in license that expires a year after the product version’s release date, as well as a production-enabled USER namespace (there are also some limitations).

Once your node is deployed, go to the page listing your nodes — Compute Engine > VM Instances (GCP), EC2 > Running instances (AWS), or Virtual machines (Azure) — then continue with the instructions in Explore Your InterSystems IRIS Instance.

Deploy InterSystems IRIS BYOL on a Cloud Node

To deploy InterSystems IRIS BYOL on a public cloud node, use the following procedure.

Note:

To request an InterSystems IRIS evaluation license, please go to https://www.intersystems.com/intersystems-iris-experience-followup/.

  1. Log into your Google Public Cloud, Amazon Web Services, or Microsoft Azure account. If neither you nor your employer have one yet, you can go to the GCP, AWS, or Azure portal page to quickly create a free account. Select or create a project (GCP), an IAM user and credentials (AWS), or a resource group (Azure).

  2. Find the InterSystems IRIS data platform BYOL page by going to the cloud provider’s marketplace page and searching for InterSystems IRIS.

  3. On the listing page, click Launch (GCP), Continue to Subscribe (AWS), or Create (Azure), follow the prompts and fill in the required fields, then click Deploy when ready.

    Note:

    On Azure, to simplify making SSH connections to the cloud node, find the Administrator account section at the bottom of the Basics tab on the Create a virtual machine page, select Password for Aunthentication type, and enter a username and password.

    On AWS, for a more streamlined experience, choose Launch through EC2 at the first prompt on the Launch this software page. (If you continue on the website, at the Security Group Settings drop-down, be sure to select Create New Based On Seller Settings.)

  4. Once your node is deployed, go to the page listing your nodes (Compute Engine > VM Instances on GCP, Virtual machines on Azure, EC2 > Running instances on AWS) and connect to the node using SSH.

  5. On the cloud node command line, list the InterSystems IRIS image with the docker images command, for example:

    user@intersystems-iris-byol-vm:~$ docker images
    REPOSITORY          TAG                  IMAGE ID            CREATED             SIZE
    intersystems/iris   2020.1.0.215.0-gcp   02c8633f381d        4 weeks ago         1.3GB
    
    Copy code to clipboard
  6. Choose a storage location in the cloud node’s file system to be mounted as an external volume in the InterSystems IRIS container; for example, you might create the directory /home/user/iris_external. Copy your InterSystems IRIS license key to that location.

    Important:

    InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers. For information about which storage locations can be mounted in this way and Docker configuration that may be required, see Use Volumes in the Docker documentation.

  7. Execute a docker run command like the following, inserting the name of your selected storage location, the image repository and tag as displayed by the docker images command, and the name of your license key:

    docker run --name iris
      --init
      --detach
      --publish 1972:1972
      --publish 52773:52773
      --volume /home/user/iris_external:/external
      intersystems/iris:2020.1.0.215.0-gcp
      --key /external/iris.key
    
    Copy code to clipboard

    This creates and starts an InterSystems IRIS container that

    • is named iris

    • publishes the instance’s superserver port (1972) and web server port (52773) to the same ports on the cloud node (the cloud node ports come first), so you can interact with InterSystems IRIS from outside the container

    • mounts the specified file system location as an external volume

    • copies the license key from the external volume to the instance’s mgr/ directory and activates it when the instance starts.

    Important:

    Whichever cloud node ports you publish to — for example, if you include --publish 9999:52773 to publish the instance’s web server port to cloud node port 9999 — be sure to note them for use in connecting to the instance.

  8. When the command has completed, use the docker ps command to see your container listed with a status of Up.

    $ docker run --name iris --init --detach --publish 1972:1972 --publish 52773:52773
        --volume /home/user/iris_external:/external
        intersystems/iris:2020.1.0.215.0-gcp --key /external/iris.key
    426d4a511d6746d89ec2a24cf93b29aa546ea696b479a52210d37da4c6d04883
    $ docker ps
    CONTAINER ID  IMAGE                                 COMMAND                 CREATED        
    426d4a511d67  intersystems/iris:2020.1.0.215.0-gcp  "/iris-main --key ..."  21 seconds ago  
        STATUS         PORTS                     NAMES
        Up 15 seconds  0.0.0.0:52773->52773/tcp  iris
    Copy code to clipboard

That’s it! You are the proud owner of a licensed InterSystems IRIS instance on a cloud node. For more detailed information about running and using InterSystems IRIS containers, see Running InterSystems IRIS Containers in Running InterSystems Products in Containers.

Once your node is deployed, go to the page listing your nodes — Compute Engine > VM Instances (GCP), Virtual machines (Azure), or EC2 > Running instances (AWS) — then continue with the instructions in Explore Your InterSystems IRIS Instance.

Explore Your InterSystems IRIS Instance

This section describes several ways to interact with your containerized Community Edition or BYOL InterSystems IRIS instance. Whichever you choose, the first step after connecting is to secure your instance by changing the instance’s default passwords.

Change the Default Passwords

To ensure that you have immediate access after installation, InterSystems IRIS comes with several predefined user accounts, each of which has the default password SYS. To secure your instance, you should change these default passwords as soon as possible.

On a cloud node, whether the instance is Community Edition or BYOL, the recommended and easiest way to do this is by connecting to the node using SSH and issuing the command iris password at the shell prompt, because this changes the default passwords for all of the predefined accounts at the same time. The command also displays the predefined account usernames; you will use one of these with the new password you just entered when you first log into the InterSystems IRIS instance.

Note:

On GCP cloud nodes, you may see an error message that begins with the following when you use iris password or the other iris utility commands:

Got permission denied while trying to connect to the Docker
  daemon socket at unix:///var/run/docker.sock ...
Copy code to clipboard

If this happens, add yourself (the user you are logged in as, as reflected in the shell prompt) to the docker group by issuing the following commands:

sudo usrmod -aG docker <username>
newgrp docker
Copy code to clipboard

The first permanently adds you to the group, effective on the next login, while the second adds you for this login session. This will also enable you to run Docker commands without prefixing them with sudo.

On any system, when you connect to a containerized instance using the Management Portal, you must log in using one of the predefined accounts, for example _SYSTEM. If it is your first time logging into this account, and you have not already changed the default password using the iris password command, you must use the default password SYS, then change the password for the account when you are prompted immediately afterwards. If your instance is not on a cloud node (where you should use iris password), change the default passwords for all of the predefined accounts as soon as possible, in either of the following ways:

Connect to the Cloud Node Using SSH

You can connect to your cloud node using SSH to change the default passwords, explore the InterSystems IRIS container, and interact with InterSystems IRIS using the InterSystems Terminal. The way in which you connect depends on the platform you are using, as follows:

  • The GCP interface includes a built-in SSH connection option; just click the SSH button for the VM instance on the Compute Engine > VM Instances page. (There are other ways to connect, as described in the GCP documentation, but this is the simplest.)

  • Azure uses the credentials you provided for the administrator account on the Create a virtual machine page when deploying the node. Follow the instructions in Connect to a Linux-based VM in the Azure documentation to connect using a separate program such as PuTTY.

  • AWS uses the public-private key pair you designated or created when launching the instance, and you must supply the program you use to make an SSH connection with the private key from this pair. You can connect with the popular program PuTTY using these steps:

    1. Open the PuTTYgen key generator program that is installed with PuTTY and do the following:

      1. Use the Load button to load the .pem private key file provided by AWS. (Remember to set the file type selector in the file browser dialog to All files (*.*) to display the .pem file you want to load.)

      2. Use the Save private key button to save the key in .ppk format.

    2. Open the PuTTY program itself and do the following:

      1. In the Host Name box, enter ubuntu@host, where host is either the DNS name or the IP address, for example ubuntu@ec2-34-000-53-213.compute-1.amazonaws.com or ubuntu@34.000.53.213.

      2. In the navigation tree on the left, expand SSH and select Auth, and at the Private key file for authentication prompt browse for the .ppk file you saved in the previous step.

      3. Click Open.

      Once you have successfully connected, you can save the connection settings in PuTTY so that fewer steps will be required to connect in the future.

    For other ways to connect to an AWS cloud node, see Connect to your linux in the AWS documentation.

Interact with InterSystems IRIS

Several ways to interact with your containerized InterSystems IRIS instance are listed in the following. The ones you’ll use depend on what InterSystems IRIS features you want to explore. For detailed information about using a containerized InterSystems IRIS instance, see Running InterSystems Products in Containers.

Note:

If you are using InterSystems IRIS on a GCP cloud node and receive an error message when you use the iris or docker commands described in the following, see the Note in Change the Default Passwords.

Interacting from the Shell

At the shell prompt on a cloud node only, you can

  • Use the special iris utility, which along with iris password includes the following commands:

    • iris status to display the status of the InterSystems IRIS instance.

    • iris info to show information about connecting to the instance.

    • iris load to load data into the instance from a specified GitHub repo.

    • iris help to list the above commands.

  • Review the Docker compose file that was used to create the InterSystems IRIS container, located at /opt/ISC/docker-compose.yml.

At the shell prompt on any system hosting the InterSystems IRIS container, cloud node or otherwise, you can

  • See how containerization makes upgrades a snap by exploring the instance-specific data stored outside the InterSystems IRIS container.

    • On the cloud node’s file system, it is in /ISC/dur.

    • On the system hosting the container you ran from the downloaded image, it is on the volume you specified with the --volume option, in the directory you specified in the ISC_DATA_DIRECTORY environment variable. For example, suppose your docker run command included these options:

      --volume /home/user/iris_external:/external
      --env ISC_DATA_DIRECTORY=/external/dur
      Copy code to clipboard

      In this case, the instance-specific data would be located in /home/user/iris_external/dur outside the container and /external/dur inside the container.

  • Issue Docker commands, including the following docker exec command to open a shell within the InterSystems IRIS container, which is called iris. (The -i option makes the command interactive and -t allocates a text terminal.)

    docker exec -it iris bash
    

    Using the container command line you can interact directly with the containerized InterSystems IRIS instance, as described in the next section, and also explore the instance’s installation directory structure.

Interact Using the InterSystems Terminal

Open a shell within the container using docker exec -it iris bash as described in the previous section, then execute the InterSystems IRIS iris command to connect to and manage the instance using the InterSystems Terminal. For example, to open a Terminal session for the instance (which is called IRIS), issue the command iris terminal IRIS. You can also do this directly from the container host’s shell with the command docker exec -it iris iris terminal IRIS.

Note:

As described in Ownership and Directories in Running InterSystems Products in Containers, commands issued from outside an InterSystems IRIS container using docker exec are executed inside the container as irisowner, and therefore do not require authentication. For this reason, you can use the commands cited above to open the InterSystems Terminal for the instance without being prompted for credentials.

You can also open the InterSystems IRIS SQL Shell by logging in as sqluser/sqluser.

Interact Using the Management Portal

To open the InterSystems IRIS Management Portal for your instance, load this URL in your browser.

http://host-IP:52773/csp/sys/UtilHome.csp

where host-IP is the IP address of the cloud node or other system hosting the container, for example http://35.192.00.154:52773/csp/sys/UtilHome.csp. 52773 is the default web server port, and this URL assumes it was published to the host as the same port. The specific link for your cloud node instance is shown when you connect to a cloud node using SSH, and you can display it at any time using the iris info command in the shell. If the container is running on your local system, you can use 127.0.0.1 or localhost in place of host-IP. If you published another host port for 52773 when you started the container, for example --publish 99999:52773, you need to use that host port instead, for example http://localhost:99999/csp/sys/UtilHome.csp.

When the portal opens, log in using _SYSTEM or one of the other predefined account usernames and

  • If you changed the default passwords using the iris password command or another method, the new password you provided.

  • If you have not yet changed the default passwords, and it is your first login to this user account, the default password SYS. You are immediately prompted to change it for that account, and should change it for the other predefined accounts as soon as possible.

The Management Portal is the comprehensive web-based user interface to an InterSystems IRIS instance. Load it in your browser to configure and manage the instance and to access the InterSystems IRIS data platform features you are interested in. For example, you can create a custom namespace and database, create resources, roles, and users for authorization and manage other InterSystems IRIS security and encryption features, and configure connectivity, national language support, and other settings. You can also explore the pages used to create and manage interoperability productions, and use the System Explorer page to examine tables, views, and stored procedures on the instance, execute SQL queries and review query plans, and review the code on the instance and the globals that provide direct programmatic access to its data. You might want to search the documentation to review everything InterSystems IRIS has to offer on a topic of interest to you.

Connect an Integrated Development Environment (IDE)

To connect an IDE to the InterSystems IRIS instance, you’ll need some or all of the following information:

  • The hostname or external IP address of the container’s host (as in the Management Portal link).

  • The instance’s superserver port, 1972, and web server port, 52773. (If you published different host ports for these InterSystems IRIS ports when you started the container, you need to use those host ports instead.)

  • Credentials to log into the instance, either one of the predefined account usernames with the default or new password as explained above for the Management Portal, or a new user account you have created using the Management Portal.

You can use a variety of IDEs to develop InterSystems ObjectScript, Python, .NET, Java, JavaScript, and Node.js code on your InterSystems IRIS instance.

Develop Applications

You can develop applications on your InterSystems IRIS instance using any or all of these tools:

InterSystems IRIS features multi-model databases, providing object, SQL, multidimensional, and document data access. Use the InterSystems JDBC driver or the InterSystems ODBC driver to load data into a database on your InterSystems IRIS instance.

The InterSystems IRIS Native APIs are lightweight interfaces that let you directly access globals, the tree-based sparse arrays that form the basis of the multimodel data access capabilities of InterSystems IRIS, from your .NET, Java, Python, or Node.js code. The Java and .NET Native APIs also enable your Java or .NET application to work with InterSystems IRIS objects as easily as if they were native Java or .NET objects.

The InterSystems API Manager (IAM) supports microservices-based applications by enabling you to monitor and direct traffic to and from your web-based APIs.

Next Steps

Where to go from here? Take your choice of a wide range of destinations. And remember, you can always contact us for information about or help with InterSystems products, including InterSystems IRIS.

InterSystems IRIS Learning Services

InterSystems IRIS data platform is supported by an extensive set of learning materials.

An Introduction to InterSystems IRIS

For high-level views of InterSystems IRIS and its capabilities, see InterSystems IRIS Overview (article) and the What is InterSystems IRIS? QuickStart.

InterSystems IRIS First Looks

These short documents introduce you to an InterSystems feature or technology and give you the chance to try it for yourself on your InterSystems IRIS cloud instance. For example, you can try the hands-on exercises in these First Looks:

There are lots more! For a full list of First Looks, see InterSystems First Looks; the Try It! icon indicates those you can use with a cloud or other containerized instance. And the InterSystems IRIS documentation thoroughly covers everything InterSystems IRIS has to offer.

InterSystems IRIS QuickStarts

With InterSystems Learning Services QuickStarts, you can see how InterSystems IRIS data platform can be used to improve your systems and benefit your applications, and access informative hands-on encounters with InterSystems technology. You can also consult a wide range of other online learning materials

Experience InterSystems Technology

Ready to try InterSystems technology for yourself? Choose an experience in your area of interest and get started.

InterSystems Developer Community

On the InterSystems Developer Community, you can read about and discuss InterSystems products and technologies, including InterSystems IRIS. Posts include articles, questions and answers, announcements, new feature descriptions, and videos. Both InterSystems employees and community members participate. Register on the Developer Community to ask questions about InterSystems IRIS functionality and architecture and get answers from the people who know!

Worldwide Response Center

The Worldwide Response Center (WRC) provides expert technical assistance with InterSystems products. The center is on call 24x7x365 with staff fluent in 15 languages.

InterSystems IRIS on the Web

You can also get immediate access to a free InterSystems IRIS Community Edition instance (with a few modifications) on the InterSystems Learning Labs web page, and use it to build an application with one of the many supported languages. Your InterSystems Labs instance comes with an integrated IDE, and several projects with sample data and step-by-step instructions. You can also connect your own IDE to the instance and use that to work with the sample data, or create data of your own that more closely reflects the specific needs of your application. The InterSystems Labs instance comes with a free built-in 90-day license, with functionality limitations similar to those of Community Edition.

InterSystems IRIS Community Edition Limitations

The InterSystems IRIS instance on the Community Edition cloud node is subject to certain limitations, as follows: