DEV Community: Anton Umnikov

Minimalistic MCP Server in bash script

Anton Umnikov — Mon, 31 Mar 2025 20:35:47 +0000

Let's create a minimalistic MCP server as a single, self-sufficient shell script.

GitHub code for this article: https://github.com/antonum/mcp-server-bash

Model Context Protocol (MPC) is a hot topic nowadays. You can find many YouTube videos and articles guiding you through creating your first MPC server with Python, TypeScript, etc.

Cool!!! But... All these examples rely on external libraries such as FastMCP for Python or McpServer for TypeScript. Essentially hiding the complexity (or the elegance if you will) of the underlying protocol from you.

For me, it's a great learning opportunity to learn the inner workings of MCP, but you can think of different use cases, such as turning your existing bash scripts into tools for LLM without giving them access to the entire system via bash.

Basic stdio server in bash

First of all - MCP works either via HTTP request or via standard Input/Output. Let's use stdio here. The bare minimum stdio server looks like this:

#!/bin/bash
while read -r line; do
    echo $line
done || break

You can save this file as test.sh and, in the terminal, run bash test.sh. The server would just repeat whatever you type until you press Ctrl^C.

JSONRPC

Not exactly what we need, but we are getting there... Instead of arbitrary text, MCP use the jsonrpc protocol. Here are the basic request and response in jsonrpc:

{
  "jsonrpc": "2.0",
  "method": "add",
  "params": [5, 3],
  "id": 1
}

{
  "jsonrpc": "2.0",
  "result": 8,
  "id": 1
}

Very simple. "jsonrpc": "2.0" tells us what specific protocol we are using and "id": 1 is an id of requests that must be matched by the server response.

Now, let's adapt our server to match the sample request and response above:

#!/bin/bash
while read -r line; do
    method=$(echo "$line" | jq -r '.method' 2>/dev/null)
    id=$(echo "$line" | jq -r '.id' 2>/dev/null)
    if [[ "$method" == "add" ]]; then
        # Parse the parameters from the JSON input
        num1=$(echo "$line" | jq -r '.params[0]' 2>/dev/null)
        num2=$(echo "$line" | jq -r '.params[1]' 2>/dev/null)

        # Perform the addition
        sum=$((num1 + num2))

        # Return the result as JSON
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"sum":'"$sum"'}}'
    else
        echo '{"jsonrpc":"2.0","id":'"$id"',"error":{"code":-32601,"message":"Method not found"}}'
    fi
done || break

You can test it by running the following in the terminal:

echo '{"jsonrpc": "2.0","method": "add","params": [5, 3],"id": 1}' | bash test.sh

{"jsonrpc":"2.0","id":1,"result":{"sum":8}}

Almost there! We now do have a functioning jsonrps stdio server that even traps [some of] the errors.

Model Context Protocol (MCP)

There has been nothing specific to MCP so far. Just arbitrary jsonrpc. Let's get MCP working. The lifecycle of MCP server can be described in two phases. Initialization and Operation.

The init phase messages look like this:

# introductions:
Client: {"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}
Server: {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"math","version":"0.0.1"}}}
Client: {"method":"notifications/initialized","jsonrpc":"2.0"}

# gather server capabilities:
Client: {"method":"resources/list","params":{},"jsonrpc":"2.0","id":1}
Server: {"jsonrpc":"2.0","id":1,"result":{"resources":[]}}
Client: {"method":"tools/list","params":{},"jsonrpc":"2.0","id":2}
Server: {"jsonrpc":"2.0","id":2,"result":{"tools":[]}}
Client: {"method":"prompts/list","params":{},"jsonrpc":"2.0","id":3}
Server: {"jsonrpc":"2.0","id":3,"result":{"prompts":[]}}

In the example above, the client (AI Host such as Claude Desktop or mcphost) and server (your bash script) "shake hands" and inform each other of their capabilities.

Hey, I'm Claude AI!
Nice to meet you! I'm math server version 0.1.0
Cool! What are your resources?
None
How about tools?
None
Prompts?
nah!

Indeed, there's nothing in our server yet, but nevertheless if only you implement these calls in your server, you'll get a fully functioning "do nothing" server.

Fully - functioning "do nothing" MCP Server

Here is our updated bash script that speaks MCP and passes the initialization step:

#!/bin/bash
while read -r line; do
    method=$(echo "$line" | jq -r '.method' 2>/dev/null)
    id=$(echo "$line" | jq -r '.id' 2>/dev/null)
    if [[ "$method" == "initialize" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"math","version":"0.0.1"}}}'

    elif [[ "$method" == "notifications/initialized" ]]; then
        : #do nothing

    elif [[ "$method" == "tools/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"tools":[]}}'
    elif [[ "$method" == "resources/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"resources":[]}}'

    elif [[ "$method" == "prompts/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"prompts":[]}}'
    else
        echo '{"jsonrpc":"2.0","id":'"$id"',"error":{"code":-32601,"message":"Method not found"}}'
    fi
done || break

Create update the test.sh with the code above and make sure to add execute permissions to the file:

chmode +x test.sh

In order to test it you'll need to either update the existing or create a new configuration file for your LLM host.

{
    "mcpServers": {
      "math": {
        "command": "/Users/anton/code/mcp-server-bash/test.sh",
        "args": []
      }
    }
  }

For Claude Desktop that file would be claude_desktop_config.json. You can access it via Claude Menu -> Settings -> Developer - Edit Config. For mcphost you can specify this file right in the command line - add the JSON code above to the file mcp_bare.json and add it to the arguments of mcphost alongside with any model that is capable of using tools. I'm using ollama with llama3.1 here.

mcphost -m ollama:llama3.1:latest --config /Users/anton/code/mcp-server-bash/mcp_bare.json

As you can see from the output, we successfully connected to the server and loaded exactly 0 tools. Which is expected.

Add a tool to add [two numbers]

And the final step - let's add a tool. This tool would accept two numbers as an input and output the sum of these two numbers. Exactly like we already did in the jsonrpc example above, but now as a proper MCP tool that you can call from the LLM.

To add a tool, you need to adjust the response to tools/list method to let the Client know what this tool does and the method signature as well as implement corresponding logic for the tools/call method.

Here is the updated response for tools/list:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "addition",
        "description": "addition of two numbers.\n\nArgs:\n    num1, num2\n",
        "inputSchema": {
          "properties": {
              "num1": {"title": "Number1","type":"string"},
              "num2": {"title": "Number2","type": "string"}
          },
          "required": ["num1","num2"],
          "type": "object"
        }
      }
    ]
  }
}

and request/response for the addition method:

Client: {"jsonrpc":"2.0","id":20, "method":"tools/call","params":{"name":"addition","arguments":{"num1":"1","num2":"2"}}}
Server: {"jsonrpc":"2.0","id":20,"result":{"content":[{"type":"text","text":"\n sum of two numbers is 3"}],"isError":false}}

Putting it all together

Here is the final result that incorporates all we learned. STDIO server, rpcjson payload going back and forth between client and server as valid MCP messages and simple kindergarden level math.

#!/bin/bash
while read -r line; do
    # Parse JSON input using jq
    method=$(echo "$line" | jq -r '.method' 2>/dev/null)
    id=$(echo "$line" | jq -r '.id' 2>/dev/null)
    if [[ "$method" == "initialize" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"math","version":"0.0.1"}}}'

    elif [[ "$method" == "notifications/initialized" ]]; then
        : #do nothing

    elif [[ "$method" == "tools/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"tools":[{"name":"addition","description":"addition of two numbers.\n\nArgs:\n    num1, num2\n","inputSchema":{"properties":{"num1":{"title":"Number1","type":"string"},"num2":{"title":"Number2","type":"string"}},"required":["num1", "num2"],"type":"object"}}]}}'

    elif [[ "$method" == "resources/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"resources":[]}}'

    elif [[ "$method" == "prompts/list" ]]; then
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"prompts":[]}}'

    elif [[ "$method" == "tools/call" ]]; then
        tool_method=$(echo "$line" | jq -r '.params.name' 2>/dev/null)
        num1=$(echo "$line" | jq -r '.params.arguments.num1' 2>/dev/null)
        num2=$(echo "$line" | jq -r '.params.arguments.num2' 2>/dev/null)
        sum=$((num1 + num2))
        echo '{"jsonrpc":"2.0","id":'"$id"',"result":{"content":[{"type":"text","text":"\n sum of two numbers is '"$sum"'"}],"isError":false}}'

    else
        echo '{"jsonrpc":"2.0","id":'"$id"',"error":{"code":-32601,"message":"Method not found"}}'
    fi
done || break

Final result:

Here you have it. The fully functioning Model Context Protocol server in bash. No dependencies, no external libraries. Just under 30 lines of code.

References

Model Context Protocol https://www.anthropic.com/news/model-context-protocol
mcphost https://github.com/mark3labs/mcphost
jsonrpc specification: https://www.jsonrpc.org/specification

Federated SQL queries to AWS S3 with InterSystems IRIS

Anton Umnikov — Mon, 07 Dec 2020 17:17:04 +0000

IRIS External Table is an InterSystems Community Open Source Project, that allows you to use files, stored in the local file system and cloud object storage such as AWS S3 as SQL Tables.

It can be found on Github https://github.com/intersystems-community/IRIS-ExternalTable Open Exchange https://openexchange.intersystems.com/package/IRIS-External-Table and is included in InterSystems Package Manager ZPM.

To instal External Table from GitHub use:

git clone https://github.com/antonum/IRIS-ExternalTable.git
iris session iris
USER>set sc = ##class(%SYSTEM.OBJ).LoadDir("<path-to>/IRIS-ExternalTable/src", "ck",,1)

To install with ZPM Package Manager use:

USER>zpm "install external-table"

Working with local files

Let’s create a simple file that looks like this:

a1,b1
a2,b2

Open your favorite editor and create the file or just use a command line in linux/mac:

echo $'a1,b1\na2,b2' > /tmp/test.txt

In IRIS SQL Create table to represent this file:

create table test (col1 char(10),col2 char(10))

Convert table to use external storage:

CALL EXT.ConvertToExternal(
    'test',
    '{
        "adapter":"EXT.LocalFile",
        "location":"/tmp/test.txt",
        "delimiter": ","
    }')

And finally – query the table:

select * from test

If everything works out as expected you should see output like:

col1    col2
a1  b1
a2  b2

Now get back to the editor, change the content of the file and rerun the SQL query. Ta-Da!!! You are reading new values from your local file in SQL.

col1    col2
a1  b1
a2  b99

Reading data from S3

At you can get access to constantly updating data on COVID, stored by AWS in the public data lake.

Let’s try to access one of the data sources in this data lake: s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states

If you have AWS command line tool installed – you can repeat the steps below. If not – skip straight to SQL part. You don’t need anything AWS – specific to be installed on your machine to follow along with SQL part.

$ aws s3 ls s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/
2020-12-04 17:19:10     510572 us-states.csv

$ aws s3 cp s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv .
download: s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv to ./us-states.csv

$ head us-states.csv 
date,state,fips,cases,deaths
2020-01-21,Washington,53,1,0
2020-01-22,Washington,53,1,0
2020-01-23,Washington,53,1,0
2020-01-24,Illinois,17,1,0
2020-01-24,Washington,53,1,0
2020-01-25,California,06,1,0
2020-01-25,Illinois,17,1,0
2020-01-25,Washington,53,1,0
2020-01-26,Arizona,04,1,0

So we have a file with a fairly simple structure. Five delimited fields.

To expose this S3 folder as the External Table – first, we need to create a "regular" table with the desired structure:

-- create external table
create table covid_by_state (
    "date" DATE, 
    "state" VARCHAR(20),
    fips INT,
    cases INT,
    deaths INT
)

Note that some field names like “Date” are reserved words in IRIS SQL and need to be surrounded by double quotes.
Then – we need to convert this “regular” table to the “external” table, based on AWS S3 bucket and CSV type.

 -- convert table to external storage
call EXT.ConvertToExternal(
    'covid_by_state',
    '{
    "adapter":"EXT.AWSS3",
    "location":"s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/",
    "type": "csv",
    "delimiter": ",",
    "skipHeaders": 1
    }' 
)

If you'll look closely - EXT.ExternalTable procedures arguments are table name and then JSON string, containing multiple parameters, such as location to look for files, adapter to use, delimiter etc. Besides AWS S3 External Table supports Azure BLOB storage, Google Cloud Buckets and the local filesystem. GitHub Repo contains references for the syntax and options supported for all the formats.

And finally – query the table:

-- query the table
select top 10 * from covid_by_state order by "date" desc

[SQL]USER>>select top 10 * from covid_by_state order by "date" desc
2.  select top 10 * from covid_by_state order by "date" desc

date    state   fips    cases   deaths
2020-12-06  Alabama 01  269877  3889
2020-12-06  Alaska  02  36847   136
2020-12-06  Arizona 04  364276  6950
2020-12-06  Arkansas    05  170924  2660
2020-12-06  California  06  1371940 19937
2020-12-06  Colorado    08  262460  3437
2020-12-06  Connecticut 09  127715  5146
2020-12-06  Delaware    10  39912   793
2020-12-06  District of Columbia    11  23136   697
2020-12-06  Florida 12  1058066 19176

It takes understandably more time to query data from the remote table, then it is for the “IRIS native” or global based table, but it is completely stored and updated on the cloud and being pulled into IRIS behind the scenes.

Let’s explore a couple of more features of the External Table.

%PATH and tables, based on multiple files

In our example folder in the bucket contains just one file. More often then not it would have multiple files of the same structure where filename identifies either timestamp or deviceid of some other attribute that we’ll want to use in our queries.

%PATH field is automatically added to every External Table and contains full path to the file where row was retrieved from.

select top 5 %PATH,* from covid_by_state

%PATH   date    state   fips    cases   deaths
s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv    2020-01-21  Washington  53  1   0
s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv    2020-01-22  Washington  53  1   0
s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv    2020-01-23  Washington  53  1   0
s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv    2020-01-24  Illinois    17  1   0
s3://covid19-lake/rearc-covid-19-nyt-data-in-usa/csv/us-states/us-states.csv    2020-01-24  Washington  53  1   0

You can use this %PATH field in your SQL queries as any other field.

ETL data to “Regular Tables”

If your task is to load data from S3 into an IRIS table – you can use the External Table as an ETL tool. Just do:

INSERT INTO internal_table SELECT * FROM external_table

In our case, if we want to copy COVID data from S3 into the local table:

--create local table
create table covid_by_state_local (
    "date" DATE, 
    "state" VARCHAR(100),
    fips INT,
    cases INT,
    deaths INT
)
--ETL from External to Local table
INSERT INTO covid_by_state_local SELECT TO_DATE("date",'YYYY-MM-DD'),state,fips,cases,deaths FROM covid_by_state

JOIN between IRIS – native and External table. Federated queries

External Table is an SQL table. It can be joined with other tables, used in subselects and UNIONs. You can even combine the “Regular” IRIS table and two or more external tables from different sources in the same SQL query.

Try creating a regular table such as matching state names to state codes like Washington – WA. And Join it with our S3-Based table.

create table state_codes (name varchar(100), code char(2))
insert into state_codes values ('Washington','WA')
insert into state_codes values ('Illinois','IL')

select top 10 "date", state, code, cases from covid_by_state join state_codes on state=name

Change ‘join’ to ‘left join’ to include rows for which state code is not defined. As you can see - the result is a combination of data from S3 and your native IRIS table.

Secure access to data

AWS Covid Data Lake is public. Anyone can read data from it without any authentication or authorization. In real life you want access your data in secure way that would prevent strangers from peeking at your files. Full details of AWS Identity and Access Management (IAM) is outside of the scope of this article. But the minimum, you need to know is that you need at least AWS Account Access Key and Secret in order to access private data in your account.

AWS Uses Account Key/Secret authentication to sign requests. https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys

If you are running IRIS External Table on EC2 instance, the recommended way of dealing with authentication is using EC2 Instance Roles https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html IRIS External Table would be able to use permissions of that role. No extra setup required.

On a local/non EC2 instance you need to specify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY by either specifying environment variables or installing and configuring AWS CLI client.

export AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY
export AWS_SECRET_ACCESS_KEY=111222333abcdefghigklmnopqrst

Make sure that the environment variable is visible within your IRIS process. You can verify it by running:

USER>write $system.Util.GetEnviron("AWS_ACCESS_KEY_ID")

It should output the value of the key.

or install AWS CLI, following instruction here https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html and run:

aws configure

External Table then will be able to read the credentials from aws cli config files. Your interactive shell and IRIS process might be running under different accounts - make sure you run aws configure under the same account as your IRIS process.

InterSystems IRIS Deployment Guide with CloudFormation Template

Anton Umnikov — Wed, 19 Aug 2020 19:35:31 +0000

InterSystems IRIS Deployment Guide – AWS Partner Network

Version 0.8, Aug 12, 2020

Anton Umnikov

Templates Source code is available here: https://github.com/antonum/AWSIRISDeployment

Introduction

InterSystems provides the _ CloudFormation Template _ for users to set up their own InterSystems IRIS® data platform according to InterSystems and AWS best practices.

This guide will detail the steps to deploy the _ CloudFormation template. _

In this guide, we cover two types of deployments for the InterSystems IRIS _ CloudFormation template _. The first method is highly available using multiple availability zones (AZ) and targeted to production workloads, and the second method is a single availability zone deployment for development and testing workloads.

Prerequisites and Requirements

In this section, we detail the prerequisites and requirements to run and operate our solution.

Time

The deployment itself takes about 4 minutes , but with prerequisites and testing it could take up to 2 hours.

Product License and Binaries

InterSystems IRIS binaries are available to InterSystems customers via https://wrc.intersystems.com/. Login with your WRC credentials and follow the links to Actions -> SW Distributions -> InterSystems IRIS. This Deployment Guide is written for the Red Hat platform of InterSystems IRIS 2020.1 build 217. IRIS binaries file names are of the format ISCAgent-2020.1.0.215.0-lnxrhx64.tar.gz and IRISHealth-2020.1.0.217.1-lnxrhx64.tar.gz

InterSystems IRIS license key – you should be able to use your existing InterSystems IRIS license key (iris.key). You can also request an evaluation key via the InterSystems IRIS Evaluation Service: https://download.intersystems.com/download/register.csp.

AWS Account

You must have an AWS account set up. If you do not, visit: https://aws.amazon.com/getting-started/

IAM Entity for user

Create an IAM user or role. Your IAM user should have a policy that allows AWS CloudFormation actions. Do not use your root account to deploy the CloudFormation template. In addition to AWS CloudFormation actions, IAM users who create or delete stacks will also require additional permissions that depend on the stack template. This deployment requires permissions to all the services listed in the following section.

Reference: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html.

IAM Role for EC2

The CloudFormation template requires an IAM role that allows your EC2 instance to access S3 buckets and put logs into CloudWatch. See Appendix "IAM Policy for EC2 instance" for an example of the policy associated with such role.

Reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html.

S3 Bucket

Create an S3 bucket called "my bucket", copy IRIS binaries files and iris.key:

BUCKET=<my bucket>
aws s3 mb s3://$BUCKET
aws s3 cp ISCAgent-2020.1.0.215.0-lnxrhx64.tar.gz s3://$BUCKET
aws s3 cp IRISHealth-2020.1.0.217.1-lnxrhx64.tar.gz s3://$BUCKET
aws s3 cp iris.key s3://$BUCKET

VPC and Subnets

The template is designed to deploy IRIS into an existing VPC and Subnets. In regions where three or more Availability Zones are available, we recommend creating three private subnets across three different AZ's. Bastion Host should be located in any of the public subnets within the VPC. You can follow the AWS example to create a VPC and Subnets with the CloudFormation template: https://docs.aws.amazon.com/codebuild/latest/userguide/cloudformation-vpc-template.html.

EC2 Key Pair

To access the EC2 instances provisioned by this template, you will need at least one EC2 Key Pair. Refer to this guide for details: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html.

Knowledge Requirements

Knowledge of the following AWS services is required:

Account limit increases will not be required for this deployment.

More information on proper policy and permissions can be found here: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html.

Note: Individuals possessing the AWS Associate certifications should have a sufficient depth of knowledge.

Architecture

In this section, we give architecture diagrams of two deployment possibilities, and talk about architecture design choices.

Multi-AZ Fault Tolerant Architecture Diagram (Preferred)

In this preferred option, mirrored IRIS instances are situated behind a load balancer in two availability zones to ensure high availability and fault tolerance. In regions with three or more availability zones, the Arbiter node is located in the third AZ.

Database nodes are located in private subnets. Bastion Host is in a Public subnet within the same VPC.

Network Load Balancer directs database traffic to the current Primary IRIS node
Bastion Host allows secure access to the IRIS EC2 instances
IRIS stores all customer data in encrypted EBS volumes
1. EBS is encrypted and uses the AWS Key Management Service (KMS) managed key
2. For regulated workloads where encryption of data in transit is required, you can choose to use the r5n family of instances, since they provide automatic instance-to-instance traffic encryption. IRIS-level traffic encryption is also possible but not enabled by CloudFormation (see the Encrypting Data in Transit section of this guide)
Use of security groups restrict access to the greatest degree possible by only allowing necessary traffic

Single Instance, Single AZ Architecture (Development and Testing)

InterSystems IRIS can also be deployed in a single Availability Zone for development and evaluation purposes. The data flow and architecture components are the same as the ones highlighted in the previous section. This solution does not provide high availability or fault tolerance and is not suitable for production use.

Deployment

Log into your AWS account with the IAM entity created in the Prerequisites section with the required permissions to deploy the solution
Make sure all the Prerequisites, such as VPC, S3 bucket, IRIS binaries and license key are in place
Click the following link to deploy CloudFormation template (deploys in us-east-1): https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=InterSystemsIRIS&templateURL=https://isc-tech-validation.s3.amazonaws.com/MirrorCluster.yaml for multi-AZ, fault tolerant deployment
In 'Step 1 - Create Stack', press the 'Next' button
In 'Step 2 - Specify stack details', fill out and adjust CloudFormation parameters depending on your requirements
Press the 'Next' button
In 'Step 3 - Configure stack options', enter and adjust optional tags, permissions, and advanced options
Press the 'Next' button
Review your CloudFormation configurations
Press the 'Create Stack' button
Wait approximately 4 minutes for your CloudFormation template to deploy
You can verify your deployment has succeeded by looking for a 'CREATE_COMPLETE' status
If the status is 'CREATE_FAILED', see the troubleshooting section in this guide
Once deployment succeeds, please carry out Health Checks from this guide

Security

In this section, we discuss the InterSystems IRIS default configuration deployed by this guide, general best practices, and options for securing your solution on AWS.

Data in Private Subnets

InterSystems IRIS EC2 instances must be placed in Private subnets and accessed only via Bastion Host or by applications via the Load Balancer.

Encrypting IRIS Data at Rest

On database instances running InterSystems IRIS, data is stored at rest in underlying EBS volumes which are encrypted. This CloudFormation template creates EBS volumes encrypted with the account-default AWS managed Key, named aws/ebs.

Encrypting IRIS data in transit

This CloudFormation does not secure Client-Server and Instance-to-Instance connections. Should data in transit encryption be required, follow the steps outlined below after the deployment is completed.

Enabling SSL for SuperServer connections (JDBC/ODBC connections): https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCAS_ssltls#GCAS_ssltls_superserver.

Durable multi-AZ configuration traffic between IRIS EC2 instances may need to be encrypted too. This can be achieved either by enabling SSL Encryption for mirroring: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCAS_ssltls#GCAS_ssltls_mirroring or switching to the r5n family of instances which provides automatic encryption of instance-to-instance traffic.

You can use AWS Certificate Manager (ACM) to easily provision, manage, and deploy Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates.

Secure access to IRIS Management Portal

By default, the IRIS management portal is accessed only via Bastion Host.

Logging/Auditing/Monitoring

InterSystems IRIS stores logging information in the messages.log file. CloudFormation does not setup any additional logging/monitoring services. We recommend that you enable structured logging as outlined here: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ALOG.

The CloudFormation template does not install InterSystems IRIS-CloudWatch integration. InterSystems recommends using InterSystems IRIS-CloudWatch integration from https://github.com/antonum/CloudWatch-IRIS. This enables collection of IRIS metrics and logs from the messages.log file into AWS CloudWatch.

The CloudFormation template does not enable AWS CloudTrail logs. You can enable CloudTrail logging by navigating to the CloudTrail service console and enabling CloudTrail logs. With CloudTrail, activity related to actions across your AWS infrastructure are recorded as an event in CloudTrail. This helps you enable governance, compliance, and operational and risk auditing of your AWS account.

_Reference: _https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html

InterSystems recommends monitoring of InterSystems IRIS logs and metrics, and alerting on at least the following indicators:

severity 2 and 3 messages
license consumption
disk % full for journals and databases
Write Daemon status
Lock Table status

In addition to the above, customers are encouraged to identify their own monitoring and alert metrics and application-specific KPIs.

Sizing/Cost

This guide will create the AWS resources outlined in the Deployment Assets section of this document. You are responsible for the cost of AWS services used while running this deployment. The minimum viable configuration for an InterSystems IRIS deployment provides high availability and security.

The template in this guide is using the BYOL (Bring Your Own License) InterSystems IRIS licensing model.

You can access Pay Per Hour IRIS Pricing at the InterSystems IRIS Marketplace page: https://aws.amazon.com/marketplace/pp/B07XRX7G6B?qid=1580742435148&sr=0-3

For details on BYOL pricing, please contact InterSystems at: https://www.intersystems.com/who-we-are/contact-us/.

The following AWS assets are required to provide a functional platform:

3 EC2 Instances (including EBS volumes and provisioned IOPS)
1 Elastic Load Balancer

The following table outlines recommendations for EC2 and EBS capacity built into the deployment CloudFormation template, as well as AWS resources costs (Units $/Month).

Workload	Dev/Test	Prod Small	Prod Medium	Prod Large
EC2 DB*	m5.large	2 * r5.large	2 * r5.4xlarge	2 * r5.8xlarge
EC2 Arbiter*	t3.small	t3.small	t3.small	t3.small
EC2 Bastion*	t3.small	t3.small	t3.small	t3.small
EBS SYS	gp2 20GB	gp2 50GB	io1 512GB 1,000iops	io1 600GB 2,000iops
EBS DB	gp2 128GB	gp2 128GB	io1 1TB 10,000iops	io1 4TB 10,000iops
EBS JRN	gp2 64GB	gp2 64GB	io1 256GB 1,000iops	io1 512GB 2,000iops
Cost Compute	85.51	199.71	1506.18	2981.90
Cost EBS vol	27.20	27.20	450.00	1286.00
Cost EBS IOPS	-	-	1560.00	1820.00
Support (Basic)	-	-	351.62	608.79
Cost Total	127.94	271.34	3867.80	6696.69
Calculator link	Calculator	Calculator	Calculator	Calculator

*All EC2 instances include additional 20GB gp2 root EBS volume

AWS cost estimates are based on On-Demand pricing in the North Virginia Region. Cost of snapshots and data transfer are not included. Please consult AWS Pricingfor the latest information.

Deployment Assets

Deployment Options

The InterSystems IRIS CloudFormation template provides two different deployment options. The multi-AZ deployment option provides a highly available redundant architecture that is suitable for production workloads. The single-AZ deployment option provides a lower cost alternative that is suitable for development or test workloads.

Deployment Assets (Recommended for Production)

The InterSystems IRIS deployment is executed via a CloudFormation template that receives input parameters and passes them to the appropriate nested template. These are executed in order based on conditions and dependencies.

AWS Resources Created:

VPC Security Groups
EC2 Instances for IRIS nodes and Arbiter
Amazon Elastic Load Balancing (Amazon ELB) Network Load Balancer (NLB)

CloudFormation Template Input Parameters

General AWS

EC2 Key Name Pair
EC2 Instance Role

Name of S3 bucket where the IRIS distribution file and license key are located

Network

The individual VPC and Subnets where resources will be launched

Database

Database Master Password
EC2 instance type for Database nodes

Stack Creation

There are four outputs for the master template: the JDBC endpoint that can be used to connect JDBC clients to InterSystems IRIS, the public IP of the Bastion Host and private IP addresses for both IRIS nodes.

Clean Up

Follow the AWS CloudFormation Deletedocumentation to delete the resources deployed by this document
Delete any other resources that you manually created to integrate or assist with the deployment, such as S3 bucket and VPC

Testing the Deployment

Health Checks

Follow the template output links to Node 01/02 Management Portal. Login with the username: SuperUser and the password you selected in the CloudFormation template.

Navigate to System Administration -> Configuration -> Mirror Settings -> Edit Mirror. Make sure the system is configured with two Failover members.

Verify that the mirrored database is created and active. System Administration -> Configuration -> Local Databases.

Validate the JDBC connection by following the "First Look JDBC" document: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=AFL_jdbc to validate JDBC connectivity to IRIS via the Load Balancer. Make sure to change the url variable to the value displayed in the template output, and password from "SYS" to the one you selected during setup.

Failover Test

On the Node02, navigate to the Management Portal (see "Health Check" section above) and open the Configuration->Edit Mirror page. At the bottom of the page you will see This member is the backup. Changes must be made on the primary.

Locate the Node01 instance in the AWS EC2 management dashboard. Its name will be of the format: MyStackName-Node01-1NGXXXXXX

Restart the Node01 instance. This will simulate an instance/AZ outage.

Reload Node02 "Edit Mirror" page. The status should change to: This member is the primary. Changes will be sent to other members.

Backup and Recovery

Backup

CloudFormation deployment does not enable backups for InterSystems IRIS. We recommend backing up IRIS EBS volumes using EBS Snapshot - https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html - in combination with IRIS Write Daemon Freeze: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCDI_backup#GCDI_backup_methods_ext.

Instance Failure

Unhealthy IRIS instances are detected by IRIS mirroring and Load Balancer, and traffic is redirected to another mirror node. Instances that are capable of recovery will rejoin the mirror and continue normal operations. If you encounter persistently unhealthy instances, please see our Knowledge Base and the "Emergency Maintenance" section of this guide.

Availability-Zone Failure

In the event of an availability-zone failure, temporary traffic disruptions may occur. Similar to instance failure, IRIS mirroring and Load Balancer would handle the event by switching traffic to the IRIS instance in the remaining available AZ.

Region Failure

The architecture outlined in this guide does not deploy a configuration that supports multi-region operation. IRIS asynchronous mirroring and AWS Route53 can be used to build configurations capable of handling region failure with minimal disruption. Please refer to https://community.intersystems.com/post/intersystems-iris-example-reference-architectures-amazon-web-services-aws for details.

RPO/RTO

Recovery Point Objective (RPO)

Single node Dev/Test configuration is defined by the time of the last successful backup.
Multi Zone Fault Tolerant setup provides Active-Active configuration that ensures full data consistency in the event of failover, with RPO of the last successful transaction.

Recovery Time Objective (RTO)

Backup recovery forthe Single node Dev/Test configuration is outside of the scope of this deployment guide. Please refer to https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-restoring-volume.html for details on restoring EBS volume snapshots.
RTO for Multi Zone Fault Tolerant setup is typically defined by the time it takes for the Elastic Load Balancer to redirect traffic to the new Primary Mirror node of the IRIS cluster. You can further reduce RTO time by developing mirror-aware applications or adding an Application Server Connection to the mirror: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GHA_mirror#GHA_mirror_set_configecp.

Storage Capacity

IRIS Journal and Database EBS volumes can reach storage capacity. InterSystems recommends monitoring Journal and Database volume state using the IRIS Dashboard, as well as Linux file-system tools such as df.

Both Journal and Database volumes can be expanded following the EBS guide https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-modify-volume.html. Note: both EBS volume expansion and Linux file system extension steps need to be performed. Optionally, after a database backup is performed, journal space can be reclaimed by running Purge Journals: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCDI_journal#GCDI_journal_tasks.

You can also consider enabling CloudWatch Agent on your instances to monitor disk space (not enabled by this CloudFormation template): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html.

Security certificate expiration

You can use AWS Certificate Manager (ACM) to easily provision, deploy, manage, and monitor expiration of Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates.

Certificates must be monitored for expiration. InterSystems does not provide an integrated process for monitoring certificate expiration. AWS provides a CloudFormation template that can help setup an alarm. Please visit the following link for details: https://docs.aws.amazon.com/config/latest/developerguide/acm-certificate-expiration-check.html.

Routine Maintenance

For IRIS upgrade procedures in mirrored configurations, please refer to: https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCI_upgrade#GCI_upgrade_tasks_mirrors.

InterSystems recommends following the best practices of AWS and InterSystems for ongoing tasks, including:

Access key rotation
Service limit evaluation
Certificate renewals
IRIS License limits and expiration https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCM_dashboard
Storage capacity monitoring https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCM_dashboard.

Additionally, you might consider adding CloudWatch Agent to your EC2 instances: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html.

Emergency Maintenance

If EC2 instances are available, connect to the instance via bastion host.

Note: The public IP of the bastion host may change after an instance stop/start. That does not affect availability of the IRIS cluster and JDBC connection.

For command line access, connect to the IRIS nodes via bastion host:

$ chmod 400 <my-ec2-key>.pem
$ ssh-add <my-ec2-key>.pem
$ ssh -J ec2-user@<bastion-public-ip> ec2-user@<node-private-ip> -L 52773:<node-private-ip>:52773

After that, the Management Portal for the instance would be available at: http://localhost:52773/csp/sys/%25CSP.Portal.Home.zenUser: SuperUser, and the password you entered at stack creation.

To connect to the IRIS command prompt use:

$ iris session iris

Consult InterSystems IRIS Management and Monitoring guide: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GCM.

Contact InterSystems Support.

If EC2 instances are not available/reachable, contact AWS Support.

NOTE: AZ or instance failures will automatically be handled in our Multi-AZ deployment.

Support

Troubleshooting

I cannot "Create stack" in CloudFormation

Please check that you have the appropriate permissions to "Create Stack". Contact your AWS account admin for permissions, or AWS Support if you continue to encounter this issue.

Stack is being created, but I can't access IRIS

It takes approximately 2 minutes from the moment EC2 instance status turns into "CREATE COMPLETED" to the moment IRIS is fully available. SSH to the EC2 Node instances and check if IRIS is running:

$iris list

If you don't see any active IRIS instances, or the message "iris: command not found" appears, then IRIS installation has failed. Check $cat /var/log/cloud-init-output.log on the instance to identify any problems with the IRIS installation during instance first start.

IRIS is up, but I can't access either the Management Portal or connect from my [Java] application

Make sure that the Security Group created by CloudFormation lists your source IP address as allowed.

Contact InterSystems Support

InterSystems Worldwide Response Center (WRC) provides expert technical assistance.

InterSystems IRIS support is always included with your IRIS subscription.

Phone, email and online support are always available to clients 24 hours a day, 7 days a week. We maintain support advisers in 15 countries around the world and have specialists fluent in English, Spanish, Portuguese, Italian, Welsh, Arabic, Hindi, Chinese, Thai, Swedish, Korean, Japanese, Finnish, Russian, French, German, Hebrew, and Hungarian. Every one of our clients immediately gets help from a highly qualified support specialist who really cares about client success.

For Immediate Help

Support phone:

+1-617-621-0700 (US)

+44 (0) 844 854 2917 (UK)

0800615658 (NZ Toll Free)

1800 628 181 (Aus Toll Free)

Support email:

support@intersystems.com

Support online:

WRC Direct

Contact support@intersystems.com for a login.

Appendix

IAM Policy for EC2 instance

The following IAM policy allows the EC2 instance to read objects from the S3 bucket 'my-bucket', and write logs to CloudWatch:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3BucketReadOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::my-bucket/*"
    },
    {
      "Sid": "CloudWatchWriteLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}