DEV Community: Ravindra Thakur

Putting a Load Balancer in Front of a Boomi Molecule on AWS

Ravindra Thakur — Mon, 26 Oct 2026 06:11:40 +0000

In an earlier post I got a two-node Boomi Molecule running on EC2, with shared storage on EFS and both nodes showing Online in Runtime Management. This post is the next step. The Molecule was up, but clients still had to pick one node's address, and if that node went down, their calls failed even though the other node was fine.

The fix is an Application Load Balancer (ALB). It gives clients one stable address, sends each request to a healthy node, and keeps checking both nodes so a stopped one drops out of rotation on its own.

I chose an ALB and not a Network Load Balancer because all the traffic here is HTTP. An NLB is for other protocols or very high throughput, and this didn't need either.

This setup was a personal proof of concept on a Boomi training environment, built to learn how Molecules work.

Account IDs, IPs, hostnames, and resource IDs are replaced with placeholders. Replace each one with the value from your own AWS and Boomi consoles as you go. The table below shows where each value comes from. The example values only show the format. They are not real.

Placeholder	Where to find it	Example format
`<VPC_ID>`	VPC console, or the EC2 console under Network	`vpc-xxxxxxxxxxxxxxxxx`
`<NODE_1_PRIVATE_IP>`, `<NODE_2_PRIVATE_IP>`	EC2 console, each instance, Private IPv4 address	`10.0.x.x` or `172.31.x.x`
`<NODE_SG_ID>`	EC2 console, Security Groups, the group your nodes use	`sg-xxxxxxxxxxxxxxxxx`
`<ALB_SG_NAME>`	The name you give the ALB security group	`demo-alb-sg`
`<ALB_DNS_NAME>`	EC2 console, Load Balancers, DNS name on the Details tab	`<name>-xxxxxxxxx.<region>.elb.amazonaws.com`
`<ENVIRONMENT_NAME>`	Boomi platform, Manage, Runtime Management	Your test environment name
`<NODE_1_NAME>`	The name you gave the first EC2 instance	`node-1`
`<YOUR_PUBLIC_IP>`	Run `curl -s https://checkip.amazonaws.com` on the machine you test from	`x.x.x.x` (add `/32` for the security group rule)

Keep these private: installer tokens, your .pem key file, AWS access keys, account IDs, and your public IP if you don't want it visible. Don't paste them into a forum post, a chat, or a screenshot. If a token is ever exposed, generate a new one.

What you need before starting

The Molecule has to be finished. Both nodes should show Online in Cluster Status, one should be the head node, and there should be no Cluster Issues tab. Both nodes should be in one security group, and that group should already allow node-to-node traffic and NFS from itself. You also need SSH access to both nodes.

Two decisions to make first. The Shared Web Server in this setup uses plain HTTP with Authentication Type set to None, which is only acceptable if nobody else can reach it. So I restricted the ALB's security group to my own public IP and never opened it to the internet. The second is cost, which I cover later, because the ALB charge keeps running even when the EC2 instances are stopped.

Here is what the setup looked like:

Item	Value
Region / VPC	`us-east-1` / `<VPC_ID>` (default VPC)
Node 1	`<NODE_1_NAME>`, private IP `<NODE_1_PRIVATE_IP>`
Node 2	`<NODE_2_NAME>`, private IP `<NODE_2_PRIVATE_IP>`
Node Availability Zone	`us-east-1b` (both nodes)
Node security group	`<NODE_SG_ID>`
Molecule environment	`<ENVIRONMENT_NAME>`

Public IPs change every time you stop and start an instance, so I don't write them down. I copy them from the EC2 console before each SSH session. Private IPs stay the same.

Part 1: Check the Shared Web Server

Open Runtime Management, go to the Molecule, and open Shared Web Server. Make sure the breadcrumb says the Molecule and not a single Atom, because that's an easy thing to get wrong.

The settings that matter here are API Type set to Advanced, port 9090, SSL unchecked, and Authentication Type set to None. The Base URL column only shows one hostname, which will be node 1's internal name. Every node listens on 9090, and the load balancer talks to each node by its private IP. That internal hostname only resolves inside AWS, so don't try to use it from your laptop.

API Type is a runtime-wide setting, and it decides how a deployed listener process turns into a URL. On Basic or Intermediate, a listener deploys with a fixed URL under /ws/simple/. On Advanced, listeners are published through an API Service Component, which builds a URL tree under /ws/rest/. This is the detail that caught me out in the first attempt. A listener process deployed by itself on an Advanced runtime deploys with no error, but the /ws/simple/ path doesn't route, and every request returns a 404. The process has to be wrapped in an API Service Component, and both must be deployed. That's why Part 2 exists.

A port change only takes effect after a restart. Save first, then restart, then wait about 90 seconds before testing. On a cluster, restart one node at a time: stop node 2, restart node 1, wait until it's green and stable for a minute, then start node 2 again.

Once the nodes are back, check each one directly on the node itself:

sudo ss -tlnp | grep 9090
curl -i http://localhost:9090/_admin/status

You want a LISTEN line for java on 9090, and a 200 OK with Content-Length: 0. The empty body is correct. /_admin/status is the health probe the load balancer will call every 15 seconds, and it only needs to return 200.

Use curl -i when you test a probe. The first time I ran it without -i, I got no output and assumed it had failed. The status code was 200 the whole time, and that's the only thing the ALB looks at.

Part 2: Build a test API

The load balancer needs something to send traffic to. I built a small test API that echoes the request and reports which node handled it. That way I could see the load balancer alternating between nodes without writing any extra scripts.

The listener process is called Molecule_GetLoadTest_Listener, and it has four steps. The first is a Web Services Server listener with an EXECUTE operation, object name GetLoadTest, single-document input and output, and text/plain as the response content type. The second is a Set Properties step that copies three values from Execution Property into dynamic document properties: Node Id, Atom Name, and Execution Id. The third is a Message step with the text Echo: {1} | Handled by node: {2} | Molecule: {3} | Execution: {4}. The fourth is Return Documents set to none. For a listener, I turned on "Allow simultaneous executions" and kept the workload at general.

Node Id is useful because the Molecule fills it in on clusters. It's the node's private IP with the dots turned into underscores, so you'll see something like 172_31_32_71 in the reply. That's the value that makes the load balancing visible.

Next, create an API Service Component. Give it any name, set the Base URL path to v1, and add a REST route that points at the listener process with the HTTP method set to POST. The effective URL is built from the base path and the object name, so the path comes out as /ws/rest/v1/GetLoadTest. The REST tab on the deployed API shows the final path, so check it there rather than trusting my arithmetic. API Management has to be enabled on your Boomi account for this component type to show up.

Deploy both pieces to the Molecule's environment, and make sure you deploy them separately. If you deploy only the API component, the deployment reports success and the routes get registered, but nothing is listening behind them, so requests still fail. If you change the process later, you have to redeploy it as well. Wait about 15 seconds after the last deployment before you test.

To confirm the API is loaded on a node, run:

curl http://<NODE_1_PRIVATE_IP>:9090/ws/rest/v1/openapi.json
curl http://<NODE_2_PRIVATE_IP>:9090/ws/rest/v1/openapi.json

Part 3: Test each node before adding the load balancer

I always test the nodes directly before I put a load balancer in front of them. If something is broken, it's much easier to find it now.

I SSH'd into node 2 with its public IP. First, a quick note on the key file. SSH refused to use it with a message about permissions being too open:

WARNING: UNPROTECTED PRIVATE KEY FILE!
Permissions 0644 for '<KEY_FILE>.pem' are too open.

The message makes it sound like a login problem, but it's just the file permissions. Run chmod 400 on the key, then run the same SSH command again.

From node 2, I ran both tests. Node 2 can reach node 1's private IP, so one session covers both nodes:

curl -i -X POST -H "Content-Type: text/plain" -d 'hello' \
  http://<NODE_1_PRIVATE_IP>:9090/ws/rest/v1/GetLoadTest
curl -i -X POST -H "Content-Type: text/plain" -d 'hello' \
  http://<NODE_2_PRIVATE_IP>:9090/ws/rest/v1/GetLoadTest

Each reply should be a 200 OK with an echo that names the node that answered. The reply has no trailing newline, so the second response gets glued onto the end of the first in the terminal. That's cosmetic.

Don't run these from your laptop. The private IPs only exist inside the AWS network, so from a laptop the connection gets reset. It's the same mistake as trying to SSH with a private IP.

If you get a 404 here, check that both the listener and the API Service Component are deployed to the Molecule's environment. If the connection is refused, the port isn't open, so go back to Part 1.

Part 4: Set up the security groups

There are two firewalls to set up. One belongs to the load balancer, and one rule on the nodes lets the load balancer in.

For the ALB's own security group, I went to EC2, then Security Groups, then Create security group. I named it <ALB_SG_NAME>, set the description, and picked the same default VPC as the nodes. For inbound, I added one rule: HTTP on port 80, with the source set to My IP. Starting with My IP is safer than "allow everyone," since the web server has no authentication yet. I left the default outbound rule alone. Removing it stops the ALB from sending traffic to the nodes.

One gotcha with My IP: it stores your address as a /32 at the moment you choose it. If your public IP changes, for example when you switch networks or turn a VPN on or off, requests will just time out. Edit the rule and pick My IP again.

Then the node side. Open the node security group, click Edit inbound rules, and add a Custom TCP rule on port 9090. For the source, don't type the group name in the Description column, because that column is just a free-text label. Use the Source search box and pick the ALB security group. It shows up as a blue tag with its sg- ID. Keep the rule from My IP that you use for direct testing.

This rule is the one people forget. The ALB sends traffic and health checks to the nodes on 9090 from inside the VPC, and without this rule those are dropped. Nothing in the console tells you clearly what's wrong. Both targets just stay unhealthy, and requests through the ALB return 503.

Part 5: Create the target group

The target group is the list of nodes the ALB can use, plus the health check that decides who's currently in rotation. In EC2, go to Target Groups and create one.

For the basics, set the target type to Instances, the protocol and port to HTTP and 9090, the protocol version to HTTP1, and the VPC to the default VPC so it matches the nodes.

For the health check, use HTTP with the path /_admin/status, the traffic port, and a success code of 200. Set the healthy threshold to 5, the unhealthy threshold to 2, the timeout to 5 seconds, and the interval to 15 seconds. With those numbers, a node that stops answering gets removed after about 30 seconds (two checks at 15 seconds each), and a node that comes back has to pass five checks in a row before it's trusted again, which takes around 75 seconds.

On the register step, select both nodes, check that the port shows 9090, and click Include as pending below. That button is easy to skip. Until you click it, the selection is only a shopping basket, and the group gets created with no targets at all. The review page should list both instances. Note their Availability Zone, because you'll need it when you create the load balancer. Both nodes were in us-east-1b.

The targets will say Unused until a load balancer points at this group. That's normal.

Part 6: Create the load balancer

In EC2, go to Load Balancers, choose Create load balancer, and pick Application Load Balancer.

Name it, make it internet-facing (it's still limited to your IP by the security group), pick IPv4, and choose the default VPC. For Availability Zones, select at least two, and make sure one of them is the zone your nodes are in. An ALB only sends traffic to targets in the zones it's enabled in. If the nodes are in us-east-1b and you leave that zone out, the targets show as unused or unhealthy and nothing reaches them.

For security groups, remove the default one the wizard pre-selects and choose the ALB group. The default group has no rule for your IP on port 80, so the ALB would be created and then be unreachable. For the listener, use HTTP on port 80 forwarding to your target group. I didn't add HTTPS, since there's no certificate in this setup.

On the review page I got a yellow warning that said the load balancer's reachability might be impacted, because the security groups didn't have the required inbound and outbound rules. I checked both tabs in the security group, and the rules were there. The warning had been calculated before I saved the rules, so it was out of date. I refreshed the security group selector and it cleared. If it doesn't clear for you, create the ALB anyway, since you can always edit the security group later without rebuilding the ALB. The warning is only harmless if you've actually checked the rules, though. If the inbound rule is missing, or it's on the wrong port, or the outbound rule was deleted, the same warning is real. Spend 30 seconds checking before you dismiss it.

Click Create. It goes into Provisioning and becomes Active after a few minutes. The DNS name on the Details tab is the address clients will use. Use it as http://<ALB_DNS_NAME>/ with no port, since the listener is on 80. AWS generates that name, and it changes every time you delete and recreate the load balancer.

I left the default attributes alone. Two of them are worth knowing about. Cross-zone load balancing is on, so requests spread across both nodes even though only one zone has nodes. Deletion protection is off, so you can delete the ALB from the console when you want to pause it.

Part 7: Check that it works

Wait for both targets to turn healthy

In Target Groups, open the target group and look at the Targets tab. Both nodes start as Initial, then should become Healthy in about two minutes. Use the refresh icon rather than reloading the whole page.

If a node stays unhealthy, the status text in its row tells you why. In my experience the usual causes are these. The security group rule from Part 4 is missing or has the wrong source. The node's own probe is failing, which you can check with curl -i http://localhost:9090/_admin/status on that node. Or the Molecule isn't running on that node, which you can check with ./atom status.

Test through the load balancer from inside AWS

This test shows the ALB works without any help from a laptop or corporate network. My first attempt timed out:

curl: (28) Failed to connect to <ALB_DNS_NAME>:80 after 134836 ms

That's a long time to wait. I had added a temporary rule to the ALB group with the source set to the node group, reasoning that node 2 was "in that group." It doesn't work that way. An internet-facing ALB's DNS name resolves to public IPs, so the node calls it over its public address, and a security group source only matches traffic from private addresses. The ALB saw a stranger on port 80 and dropped the packets silently. That's why it looked like a timeout.

The fix is to allow the node's public IP. You can find it by asking the node itself:

curl -s https://checkip.amazonaws.com

Don't use the public IP from the EC2 console, because it may have changed since you last looked. Then add a new rule with HTTP on port 80, a Custom source, and that address with /32. Trying to edit the old rule and switch its source to an IP won't work. The console refuses, because a rule's source type can't be changed once it exists. Delete the old rule and add a new one.

Always add --max-time 10 to your curl commands while you're testing. Without it, a blocked request can hang for more than two minutes. With it, a firewall problem fails in 10 seconds, which is much easier to live with.

Once the rule was right, the same commands worked:

curl -i --max-time 10 http://<ALB_DNS_NAME>/_admin/status

for i in 1 2 3 4 5 6; do
  curl -s --max-time 10 -X POST -H "Content-Type: text/plain" -d 'hello' \
    http://<ALB_DNS_NAME>/ws/rest/v1/GetLoadTest
  echo
done

The status call returned 200. The six requests were answered by both nodes, and the split wasn't strictly alternating. The ALB picks a healthy target for each request, so that's normal. When you're done testing, delete the temporary rule for your node's public IP.

Test from your laptop

From my Mac, the same request failed with a reset, not a timeout:

curl: (56) Recv failure: Connection reset by peer

A timeout would mean the security group is blocking you. A reset means something answered and then cut the connection. Running curl -v and nslookup showed that the hostname resolved to a carrier-grade NAT address, not an AWS address, so security software on my laptop was intercepting the request. The ALB itself was fine, since it had worked from inside AWS. Once I turned the client off for the test, the laptop requests worked.

If you hit this, don't just leave the protection off. Ask your IT or security team to allow the ALB hostname. Also remember that the security group needs your current public IP, and if your VPN changes it, the symptom goes back to a timeout.

Confirm the work is actually shared

The replies already show which node handled each request, but the best check is in the platform. Open Process Reporting, find the listener process, and look at the executions. Each request through the ALB makes one execution, and the execution details should show both node IDs. That's the final proof that the cluster is splitting the work.

What I'd still do before using this for real

I haven't tested failover yet. The plan is to stop node 2 and then send the six-request loop again. Every reply should come from node 1 after about 30 seconds. Then I'd start node 2 back up and confirm it returns to the pool after about 75 seconds. This is the test that actually matters, because the whole point is that clients keep working when a node disappears. I'll update this post once I've run it.

Authentication is the other thing. Right now the Shared Web Server has no authentication, so anyone who can reach the ALB can call the API. Before anyone else uses this, switch the authentication type on the port row (Basic is a reasonable start), do a rolling restart, and confirm the health check still returns 200. Without a 200 from /_admin/status, the nodes will stay unhealthy.

HTTPS needs a certificate from AWS Certificate Manager for a name you own. You'd add a 443 listener and open 443 in the ALB's security group. Until then, the listener has to stay on 80.

Keep the ALB security group narrow. My IP is fine for testing, but don't open it to 0.0.0.0/0 while authentication is off.

Cost, and how to pause

This is the part that surprised me most. An ALB is billed by the hour for as long as it exists, plus a usage charge, and you can't stop or pause it. Stopping the EC2 instances does nothing to the ALB charge. The target group and security groups are free, so the cheap way to pause is to delete only the ALB and recreate it later with the same settings.

To pause, delete the ALB from its Actions menu, and keep the target group and both security groups. Then stop the Molecule on each node, starting with the member node and finishing with the head node. Run ./atom stop and then ./atom status to confirm it's really down. After that, stop both EC2 instances in the console.

To resume, start both instances. Their public IPs will have changed, but the private IPs won't. Check EFS is still mounted (df -h /mnt/boomi, and run sudo mount -a if it isn't). Start node 1, wait for it to go green and stay stable for a minute, then start node 2. Confirm both nodes show Online in Cluster Status. Then create a new ALB with the same settings, but pick the existing target group and security group instead of making new ones. The DNS name will be different this time, so copy the new one, wait for both targets to turn healthy, and run the tests again.

When the experiment is over, delete in this order: the ALB, then the target group, then any leftover security group rules, then the ALB security group, which can't be deleted while the ALB is still using it. After that, follow the teardown steps for the nodes, EFS, and the Molecule.

Mistakes I made, or nearly made

Private key permissions: SSH refused the key because the file was readable by other users. Run chmod 400 once.
Using an old public IP: Public IPs change when you stop and start instances, so always copy the current one.
Not restarting after changing the port: Nothing listens on 9090 until you restart. Save, restart, wait 90 seconds.
Testing a probe without -i: An empty output looks like a failure, but a 200 with no body is correct.
Building only the listener on an Advanced runtime: Every URL returns 404. Wrap it in an API Service Component and deploy both.
Deploying only the API component: The deployment says it worked, but requests still fail. Deploy the process too.
Testing from your laptop with private IPs: The connection gets reset. Test from a node.
Leaving the default security group on the ALB: The ALB exists but nothing can reach it.
Not allowing the ALB into the node group on 9090: Both targets stay unhealthy, and the ALB returns 503.
Typing the group name in the Description column: The rule saves but does nothing. The group goes in the Source search box.
Skipping "Include as pending below" in the target group: The group gets created with no targets.
Registering the wrong port: The group has to be on 9090, not 80.
Leaving out the nodes' Availability Zone: Targets stay unused or unhealthy.
Ignoring the reachability warning: Check the inbound and outbound rules before you dismiss it.
Allowing a security group source for an internet-facing ALB: The ALB sees traffic from a public address and drops it. Allow the node's public IP as a /32 instead.
Trying to edit a group-source rule into an IP rule: Delete it and add a new one.
Running curl without --max-time: A blocked request hangs for minutes. Always set it.
Assuming an ALB can be paused: It keeps billing. Delete it and recreate it when you need it.

Quick reference

On your laptop, chmod 400 <key>.pem fixes the key permission problem, and ssh -i <key>.pem ec2-user@<PUBLIC_IP> opens a session on a node. curl -i http://<ALB_DNS_NAME>/_admin/status checks the probe through the ALB, and curl -v --max-time 15 shows exactly which IP you connected to. nslookup <ALB_DNS_NAME> tells you which address the name resolved to.

On a node, curl -i http://localhost:9090/_admin/status checks the local probe, curl -s https://checkip.amazonaws.com prints the node's public IP, and sudo ss -tlnp | grep 9090 shows whether java is listening. From /mnt/boomi/Molecule_<name>/bin, ./atom start, ./atom stop, ./atom restart, and ./atom status control the node.

In the console, Target Groups shows health for each node and the reason when one fails, Load Balancers shows the DNS name and listener state, and Security Groups holds the ALB group and the node's 9090 rule.

When something breaks, a 404 usually means the process or API component isn't deployed to this environment, or the URL path is wrong. A 502 or 503 from the ALB means no healthy target, so check the target group status text. A timeout means a firewall dropped the packets. A reset means something in between cut the connection, which is often security software on the laptop. The container logs for each node are under the Molecule's logs folder, and searching them for sharedServer, jetty, or ws/rest will find most startup problems.

Closing

Once I had both targets healthy and the ALB handing requests to both nodes, the setup finally felt like a cluster and not just two machines. The mistakes above were the real time sink. Most of them come down to the same few things: security group sources, public versus private addresses, and skipping a step that doesn't give you any error message. If you hit something different, I'd like to hear about it.

Installing a Boomi Molecule on AWS EC2, Part 2: Unicast Clustering and the Web Server

Ravindra Thakur — Wed, 21 Oct 2026 14:49:40 +0000

This is part 2 of a two-part series. If you haven't done it yet, read Part 1 first. Part 1 covers building the EFS and EC2 infrastructure and running the Molecule installer. This part picks up once both nodes are installed and mounted on the same shared folder.

Part 5: Switch the cluster to unicast

Why this step exists

When a Molecule node starts, it needs to find the other nodes. Boomi's default is multicast. The node sends a "who's out there?" message to a special group address and port, and any other node on the same network replies. That works on an office LAN. AWS doesn't carry multicast traffic, though. The message goes nowhere, each node decides it's alone, and each one declares itself the head of its own one-node cluster.

Unicast replaces the broadcast with an explicit list: these are the nodes in this cluster, at these addresses, listening on TCP port 7800. Two settings control it:

Setting in the platform	Property name in the config file	Value
Cluster Network Transport Type (older name: Cluster Communication Method)	`com.boomi.container.cluster.type`	`UNICAST`
Initial Hosts for Unicast	`com.boomi.container.cluster.initialHosts`	`<NODE_1_PRIVATE_IP>[7800],<NODE_2_PRIVATE_IP>[7800]`

The list uses the private IPs, each followed by [7800], separated by commas with no spaces. It doesn't have to include every node, just enough that at least one is always running. I listed both for simplicity.

Set it in the platform, not in the file

The reliable way is through the platform UI, and it needs the Molecule to be online first. That creates a small chicken-and-egg sequence:

Start node 1 only. Wait until it shows green in Runtime Management. On its own it will run in multicast mode, which is fine for now because nothing else is trying to join.
In Runtime Management, click the Molecule, then open Properties and the Advanced tab.
The Advanced tab has a long alphabetical dropdown. Scroll to the C section, select Cluster Network Transport Type, and set it to UNICAST.
Open the dropdown again, scroll to the I section, select Initial Hosts for Unicast, and enter the list of private IPs.
Save. The platform pushes the values to the runtime and writes them to the config file on EFS.
Restart node 1 with ./atom restart. The cluster layer only switches transport after a restart.

Common mistake: editing the config file by hand while the Molecule is offline. That's exactly what I tried first, adding the two lines to container.properties with echo. The lines were there when I checked. But when node 1 started, it registered with the platform, the platform pushed its own copy of the properties (which didn't have my lines), and my edits were overwritten. The node came up in multicast mode. The platform is the source of truth for runtime properties, so set them in the UI.

Common mistake: looking for the old property name. Older guides call this setting "Cluster Communication Method." In current versions it's listed as Cluster Network Transport Type. The dropdown is alphabetical, so scroll rather than searching.

Leave Cluster Network Bind Address unset. The node binds to its private IP automatically, and the log confirms that with a line about jgroups.bind_addr.

Check which mode a node is really in

Don't rely on the settings page alone. Look at the ports the Java process has open:

sudo ss -tulnp | grep java

ss lists sockets. -t is TCP, -u is UDP, -l shows listening ports only, -n shows port numbers instead of names, and -p shows which process owns each one.

What you see	What it means
A UDP line for `228.10.10.10:45588`	Still in multicast mode. The unicast settings haven't taken effect
A TCP LISTEN line for `<private-ip>:7800`	Unicast. The node is listening for the other nodes on the cluster port

This check is what finally showed me the real problem, which I describe in Part 6.

Part 6: Start the nodes and form the cluster

Start node 1

On node 1:

cd /mnt/boomi/Molecule_<YOUR_NAME>/bin
./atom start

The bin folder holds the control script. Despite the name, atom is also the script for Molecules. Wait about a minute, then check:

./atom status

It prints atom is running. or atom is not running. In Runtime Management, the Molecule should turn green.

Start node 2

Node 2 never runs the installer, because the installation is already on the shared disk. It just starts the same script:

cd /mnt/boomi/Molecule_<YOUR_NAME>/bin
./atom start

Do this only after node 1 is green, the unicast settings from Part 5 are in place, and node 1 has been restarted with them. Then wait two minutes and open Runtime Management, then the Molecule, then Cluster Status.

What success looks like

You should see two rows, both Online, with a star next to exactly one Node ID. That star marks the head node. There should be no Cluster Issues tab. Take a screenshot for your records.

Problem: MULTIPLE_HEAD_NODES

This is the problem most people hit on their first AWS Molecule, and it's exactly what happened to me. The Cluster Issues tab showed a severe warning, MULTIPLE_HEAD_NODES, with each node reporting a different head node.

It means each node wrote a small "view snapshot" file into the bin/views folder on the shared disk, recording who it thinks the cluster members are and who the head is. The platform compares those files. In my case each file said "I'm the head, and I'm the only member." So the two nodes weren't talking to each other at all. They were two separate one-node clusters sharing a disk. That's dangerous, because both will try to run the same scheduled work and write to the same execution folders.

There are only three possible causes, so check them in this order, from cheapest to most involved:

The nodes are still in multicast mode, so discovery messages never arrive. This was my actual cause.
The network between the nodes is blocked, either because one instance is in the wrong security group or the self-referencing rule is missing.
The nodes started too close together, or node 2 started before node 1 finished forming the cluster, and stale snapshot files kept the wrong state alive.

Start with a clean stop. Stop node 2, then node 1, so nothing changes while you investigate:

cd /mnt/boomi/Molecule_<YOUR_NAME>/bin
./atom stop

Check that the settings reached the runtime. The config file is on the shared disk, so either node will show the same thing:

grep -i cluster /mnt/boomi/Molecule_<YOUR_NAME>/conf/container.properties

You want to see cluster.type=UNICAST and an initialHosts line. If they're missing, go back to Part 5 and set them in the UI. In my case they were there, which was misleading, and the next check showed why.

Check the network in both directions. From node 2, run ping -c 3 <NODE_1_PRIVATE_IP>, and from node 1, run ping -c 3 <NODE_2_PRIVATE_IP>. The -c 3 option sends three packets and stops. If you see 0% packet loss, the security group is letting the nodes reach each other. If you see 100% loss, one instance isn't in the shared security group. Fix it under EC2, then Instances, then Actions, then Security, then Change security groups.

Check what the running node is actually doing. Start node 1 and wait a minute, then run sudo ss -tulnp | grep java. In my case the output showed a UDP line for the multicast address and no TCP 7800 at all. So the node was still in multicast mode, even though the file said UNICAST. The platform sync had overwritten my hand edits, and setting the properties through the UI fixed it. Once I'd done that and restarted node 1, ss showed a TCP LISTEN on port 7800, and node 2 joined.

You can also test the cluster port directly from the other node:

sudo yum install nmap-ncat -y
nc -zv <NODE_1_PRIVATE_IP> 7800

nc -z opens a connection and closes it without sending data. -v tells you what happened. A "connection refused" while ss shows nothing on port 7800 means the service isn't listening, which is a configuration problem. A "connection refused" or timeout while ss does show 7800 means a firewall problem.

Finish with an ordered restart, so no stale state survives:

# on node 2, then node 1
./atom stop

# once, from either node: clear the old snapshot files
rm -f /mnt/boomi/Molecule_<YOUR_NAME>/bin/views/*.dat

# on node 1
./atom start
# wait until green in Runtime Management, then wait one more full minute
sudo ss -tlnp | grep 7800   # must show java on 7800 before you continue

# on node 2
./atom start

Deleting the .dat files is safe, because they're regenerated within a minute. Skipping the wait between node 1 and node 2 is what creates the race condition in cause 3.

Problem: NODE_JAVA_HOME_MISMATCH

Right after the cluster formed, another warning appeared: NODE_JAVA_HOME_MISMATCH, saying node 2 was out of sync with the current Java home.

Read the bracket in the message first. It says node 2 is reporting that node 1 is the head. That's good news, because it means MULTIPLE_HEAD_NODES is resolved.

The remaining issue comes from the "store runtime assets locally" choice during installation. Each node keeps its own copy of the Java runtime. Node 1's copy was created by the installer, but node 2's was created when it first started and hadn't been marked current yet. Restarting node 2 refreshes it:

# on node 2
./atom stop
./atom start

If the warning comes back, force node 2 to rebuild its local copy from the shared installation:

./atom stop
rm -rf /home/ec2-user/boomi_local/*
./atom start

This deletes only node 2's local cache. It never touches the shared installation.

Part 7: Configure the Shared Web Server

A Molecule doesn't listen on any inbound HTTP port until you configure one. Until you do, the API Management page warns that no listener ports are set, and curl http://localhost:9090 on a node says it can't connect.

Set the port in the platform

In Runtime Management, open the Molecule, then Shared Web Server. Check that the breadcrumb at the top names the Molecule, not an individual Atom. Under Listening Port Configuration, add a row with port 9090, SSL unchecked, and Authentication Type set to None. That's fine for testing only. Scroll to the bottom and save.

Restart the nodes

A new listener port only opens at startup, so both nodes have to restart. In a cluster, restart one node at a time so the Molecule stays online:

# on node 2
./atom stop

# on node 1
./atom restart
# wait until green, plus one more minute

# on node 2
./atom start

A Molecule node takes longer to come up than an Atom, so be patient.

Verify on each node

sudo ss -tlnp | grep 9090
curl http://localhost:9090

You want a LISTEN line owned by java on port 9090. The curl should return an HTML page reading Error 404 NOT_FOUND. That 404 is the correct result. It proves the web server is running. There's just nothing deployed at the root path yet.

A note on the Base URL column: it shows node 1's hostname, but every node opens the port, so requests to node 2's IP on 9090 work the same way. A load balancer in front of the nodes is what gives clients one address. You don't need it for testing.

Problem: the port didn't open after the restart

On my first restart, ss only showed port 7800 and a random port, and curl couldn't connect. The setting was in the config file, though.

The container log explained why. The web server libraries loaded at one time, and about five minutes later the log printed the full property set, including sharedServer.http.connector.0.port=9090. The property arrived after the restart, because I'd saved the change in the UI after restarting the node, not before. The runtime accepted the new value, but a listener port only binds at startup.

The fix was another restart on each node, followed by a 90-second wait. The rule is: save first, restart second, then wait a full 90 seconds before you check.

If the port still doesn't show up after a correctly ordered save and restart, try deploying a listener process to the Molecule and check again. On some versions the shared web server doesn't bind until at least one Web Services Server process is deployed.

Part 8: Next steps

With the cluster online and the web server listening, the Molecule is ready for real work. These are the next things I plan to do.

Deploy a test listener. A simple one is a Start step set to Web Services Server with a REST resource and POST, a Message step, and Return Documents. Deploy it to the Molecule's environment. Because the Molecule lives in a different account from my original Atom, I had to rebuild the process there.
Load-test each node separately. Run Autocannon from inside a node, pointing it at each node's private IP one at a time. Then check Process Reporting. Executions should show both node IDs, which proves the cluster is actually sharing work.
Put a load balancer in front. An Application Load Balancer with a target group containing both nodes on port 9090 gives you one stable URL and spreads requests across the nodes. That's the production shape of a Molecule. I cover this in the next post.
Turn on HTTPS and authentication on the Shared Web Server before exposing anything beyond a test network.

Day-to-day operation

Stopping for the day

Order matters in a cluster. Stop the member node first and the head node last, so the head doesn't spend time re-electing itself. On node 2, run ./atom stop and then ./atom status to confirm it's down. Then do the same on node 1.

Then, in the AWS Console, go to EC2, then Instances, select both nodes, and choose Instance state, then Stop instance. Stopping ends the compute charge, which is almost all of the cost. EFS, the security group, and the key pair are left alone.

Resuming

Start both instances in the console. Their public IPs will have changed, so copy the new ones for SSH. The private IPs are the same, so the unicast list still works.
On each node, run df -h /mnt/boomi to confirm EFS came back through /etc/fstab. If it didn't, run sudo mount -a.
On node 1, run ./atom start and wait for green plus one minute.
On node 2, run ./atom start.
Check Cluster Status.

Pause versus tear down

	Stop instances	Terminate instances and delete EFS
Compute charge	None	None
Storage charge	Root disks of stopped instances plus EFS, a few rupees per day	None
Molecule preserved?	Yes, exactly as you left it	No, you'll need a full reinstall
When to choose it	Pausing for days or weeks	When the experiment is finished

If you terminate, also release any Elastic IPs, delete leftover EBS volumes and snapshots, and remove the Molecule from Runtime Management so it doesn't stay behind as an offline runtime.

Common mistakes, in the order they happen

Stage	Mistake	Symptom	Fix
Before you start	Not checking the Molecule licence count	Installer fails at "Retrieving Container ID" and rolls back	Check Licensing first, free a slot, or use another account
Before you start	Downloading from the wrong Boomi account	Molecule shows up in the wrong account, or the token is rejected	Switch accounts, generate the token there, reuse the installer
Security group	Leaving the description blank	The form won't submit	Type any text
Security group	Adding self-referencing rules during creation	"CIDR block, a security group ID or a prefix list has to be specified"	Create with SSH and 9090 first, then add the two self-referencing rules by editing
Security group	Typing the group name in the Description column	Rule saves but does nothing	Put the group in the Source search box
EFS	Mounting before the targets are Available or before attaching the security group	Mount hangs, then "Connection timed out"	Wait for Available, then assign the group under Network, then Manage
EFS	Missing `.efs` in the DNS name, or stray backticks	"Failed to resolve server"	Copy the DNS name from the EFS console exactly
SSH	Using the private IP from your laptop	Connection reset by peer	Use the public IP
SSH	Your laptop's IP changed since the rule was created	Operation timed out on port 22	Edit the SSH rule's source to My IP again
SSH	Running `ssh` or `scp` while already on a server	Key file not accessible, or cannot stat the local file	Read the prompt, and run `ssh` and `scp` from your laptop
Terminal tabs	Losing track of which tab is which node	Commands run on the wrong machine	Quit the app, reconnect deliberately, and check each prompt
scp	Leaving off `:~/` at the end of the destination	Copy fails or goes to the wrong place	Use `user@host:~/`
Installer	Typing an email or token at a `[1]` or `[2]` prompt	The prompt repeats	Type the digit
Installer	Choosing option 1 when you meant a token	Asked for a username and password	Press Ctrl+C, run again, answer `2`
Installer	Typing the environment name or ID instead of its number	The list reprints	Type the number in brackets
Installer	Typing `y` at a `[1]` or `[2]` prompt	The prompt repeats	Type `1` or `2`
Installer	Pressing Enter on a required field with empty brackets	"... is required," then loops back	Type the value
Installer	Accepting the default installation directory	Node 2 has nothing to start	Install under `/mnt/boomi`
Installer	Node 2's `boomi_local` folder not created	Node 2 fails to start or reports a missing local directory	`mkdir -p /home/ec2-user/boomi_local` on every node
Unicast	Leaving multicast on	MULTIPLE_HEAD_NODES, and the nodes never join	Set Cluster Network Transport Type to UNICAST and set the initial hosts
Unicast	Editing `container.properties` by hand	The lines are there, but the node is still in multicast mode	The platform overwrites the file on sync. Set the properties in the UI, then restart
Unicast	Searching for the old property name	Can't find "Cluster Communication Method"	It's now called Cluster Network Transport Type
Unicast	Using public IPs in the initial hosts list	Nodes can't connect on 7800	Use private IPs
Start-up	Starting node 2 too soon after node 1	MULTIPLE_HEAD_NODES from stale snapshots	Wait for green plus a minute, delete `bin/views/*.dat`, and restart in order
Cluster	NODE_JAVA_HOME_MISMATCH after joining	Severe issue on node 2	Restart node 2, and if needed clear its `boomi_local` folder
Web server	Restarting before saving the port	9090 never opens	Save first, restart, then wait 90 seconds
Web server	Treating the root-path 404 as a failure	Confusion	A 404 from `/` means the web server is up

Command reference

On your laptop

Command	What it does
`chmod 400 ~/Downloads/<KEY_FILE>.pem`	Makes the key file readable only by you. SSH refuses keys with looser permissions. Run this once
`ssh -i ~/Downloads/<KEY_FILE>.pem ec2-user@<PUBLIC_IP>`	Opens a terminal on a node. `-i` selects the key file
`scp -i ~/Downloads/<KEY_FILE>.pem <local-file> ec2-user@<PUBLIC_IP>:~/`	Copies a file from your laptop to the node's home folder

On the nodes: setup

Command	What it does
`sudo yum update -y`	Updates the operating system packages. `-y` answers yes to prompts
`sudo yum install java-17-amazon-corretto nfs-utils -y`	Installs a system Java and the NFS client tools
`sudo mkdir -p /mnt/boomi`	Creates the folder the shared disk attaches to. `-p` creates parent folders and doesn't complain if the folder exists
`sudo mount -t nfs4 -o nfsvers=4.1 <EFS_DNS_NAME>:/ /mnt/boomi`	Attaches the root of the EFS file system to `/mnt/boomi` using NFS 4.1
`df -h /mnt/boomi`	Shows what's mounted at that path and how much space it has
`echo ":/ /mnt/boomi nfs4 nfsvers=4.1,_netdev 0 0" \	sudo tee -a /etc/fstab`
`sudo mount -a`	Mounts everything listed in `/etc/fstab` that isn't already mounted
`sudo chown ec2-user:ec2-user /mnt/boomi`	Makes `ec2-user` the owner of the shared folder
`touch <file>`, `ls <dir>`, `rm <file>`	Create an empty file, list a folder, or delete a file
`mkdir -p /home/ec2-user/boomi_local`	Creates the per-node local assets folder

On the nodes: installer

Command	What it does
`chmod u+x molecule_install64.sh`	Gives the downloaded installer permission to run
`./molecule_install64.sh`	Runs the installer. The `./` is needed because the script isn't on the PATH
Ctrl+C	Cancels a running command. It's safe to use before the installer's summary screen

On the nodes: Molecule control

Run these from /mnt/boomi/Molecule_<YOUR_NAME>/bin.

Command	What it does
`./atom start`	Starts this node
`./atom stop`	Stops this node cleanly
`./atom restart`	Stops, then starts
`./atom status`	Prints whether this node is running

On the nodes: diagnostics

Command	What it does
`sudo ss -tlnp`	Lists TCP ports that are listening, and which process owns each
`sudo ss -tulnp \	grep java`
`ping -c 3 <private-ip>`	Sends three packets to the other node to test basic reachability
`nc -zv <private-ip> 7800`	Tests whether a TCP connection to the cluster port succeeds. Install it with `sudo yum install nmap-ncat -y`
`grep -i cluster .../conf/container.properties`	Shows the cluster settings the runtime currently holds
`grep -r 9090 .../conf/`	Finds any file under `conf` that mentions the port
`grep -i -E "pattern1\	pattern2" \
{% raw %}`tail -50 <logfile>`	Shows the last 50 lines of a file
`rm -f .../bin/views/*.dat`	Deletes the cluster snapshot files. They regenerate on start. Use this to clear stale head-node state

Appendix A: How to read installer prompts

Every question the console installer asks follows one of three patterns. Once you recognize them, most of the installer mistakes go away.

Pattern	Example	What to type
Options with characters in brackets	User Name and Password [1, Enter], Token [2], or Yes [y, Enter], No [n]	Exactly the character in the brackets. Nothing else is accepted. The option marked Enter is the default
A default value in brackets	Choose an installation directory [/home/ec2-user/...]	Enter to accept the default, or type a replacement
Empty brackets	Token [] or Working Data Local Storage Directory (required) []	There's no default. Type the value. Enter on its own gets rejected

If a prompt keeps repeating, you've given it something it doesn't recognize. Look at the brackets again.

Appendix B: Where the logs are

All of these paths are under the shared installation, so you can read them from either node.

Path	Contents
`/mnt/boomi/Molecule_<YOUR_NAME>/logs/YYYY_MM_DD.container.<node-id>.log`	One container log per node per day. The node ID is the private IP with underscores, for example `<NODE_ID>`. This is the first place to look for cluster and web server problems
`/mnt/boomi/Molecule_<YOUR_NAME>/conf/container.properties`	The runtime properties as last synced from the platform
`/mnt/boomi/Molecule_<YOUR_NAME>/bin/views/*.dat`	Cluster snapshot files, one per node
`/home/ec2-user/boomi_local/` (on each node)	Per-node local copies of the Java runtime, libraries, and working data

Useful search terms for the container log are cluster, unicast, multicast, MULTIPLE_HEAD_NODES, jgroups.bind_addr, sharedServer, jetty, and 9090. Searching for Container Properties for account shows the full property set at the moment the platform pushed it, with a timestamp you can compare to your restart time.

Closing

Getting the cluster to form was the hardest part. Most of the problems came from one thing: the nodes couldn't see each other, and the cause wasn't obvious from the error messages. The fix was switching to unicast through the UI, checking the actual open ports rather than trusting the settings page, and restarting in the right order.

In the next post I'll put an Application Load Balancer in front of these two nodes, so clients get one address and keep working when a node goes down.

Installing a Boomi Molecule on AWS EC2, Part 1: Infrastructure and Installer

Ravindra Thakur — Sun, 18 Oct 2026 16:42:02 +0000

What this post covers

This is part 1 of a two-part series. Part 1 covers the infrastructure and the installer. Part 2 covers switching the nodes to unicast, forming the cluster, and configuring the web server.

I installed a Boomi Molecule on two EC2 instances in September 2026 and took it from empty AWS infrastructure to a working two-node cluster, with both nodes online in Atom Management. This is the first post in a short series.

I've written this the way I actually did it, including the parts that went wrong. Most of the mistakes below are ones you're likely to make too, so I've pointed them out where they happened.

This setup was a personal proof of concept on a Boomi training environment, built to learn how Molecules work.

Every account-specific value has been replaced with a placeholder such as <NODE_1_PRIVATE_IP> or <EFS_DNS_NAME>. Replace each one with the value from your own AWS and Boomi consoles as you go. The table below shows where each value comes from. The example values are only there to show the format. They are not real.

Placeholder	Where to find it	Example format
`<EFS_DNS_NAME>`	EFS console, your file system, DNS name box on the right	`fs-xxxxxxxxxxxxxxxxx.efs.<region>.amazonaws.com`
`<NODE_1_PRIVATE_IP>`, `<NODE_2_PRIVATE_IP>`	EC2 console, each instance, Private IPv4 address	`10.0.x.x` or `172.31.x.x`
`<NODE_1_PUBLIC_IP>`	EC2 console, each instance, Public IPv4 address (changes after stop and start)	`x.x.x.x`
`<KEY_FILE>`	The `.pem` file you downloaded when you created the key pair	`my-key-name.pem`
`<YOUR_NAME>`	Any short label you choose for the Molecule installation folder	`Molecule_demo`
`<YOUR_MOLECULE_NAME>`	Any name you choose for the Molecule in Boomi	`demo-molecule`

Keep these private: installer tokens, your .pem key file, your AWS access keys, account IDs, and the full contents of container.properties. Don't paste them into a forum post, a chat, or a screenshot. If a token is ever exposed, generate a new one.

What a Molecule is, and why AWS needs a different setup

A Boomi Atom is a single-server runtime. A Molecule is the clustered version: two or more servers (called nodes) that share one installation folder on a network file system and show up in the Boomi platform as a single runtime. Work is spread across the nodes, and if one node goes down, the others keep going.

That shared-folder idea is what makes installing a Molecule different from an Atom. You need four things:

A shared disk that every node can read and write. On AWS that's Amazon EFS.
Two or more servers. One node is just an Atom with extra steps.
A network path between the nodes, since they constantly talk to each other to agree on which node is the head node.
A way for the nodes to find each other. Boomi's default method, multicast, doesn't work on AWS, so you have to switch to unicast. I explain why in Part 5.

The finished setup looks like this:

      Boomi AtomSphere platform (control plane)
                      ^
                      | outbound HTTPS from each node
        +-------------+-------------+
        |                           |
+-------+---------+       +---------+-------+
| EC2 node-1      | 7800  | EC2 node-2      |
| <NODE_1_PRIVATE_IP> <--> <NODE_2_PRIVATE_IP> |
| head node       |       | member node     |
+-------+---------+       +---------+-------+
        |  NFS 2049                 |
        +-------------+-------------+
                      |
              +-------+-------+
              |  Amazon EFS   |
              |  /mnt/boomi   |
              +---------------+

Before you start

Check your Molecule licence

Molecule licences are counted per Boomi account, and the installer checks the count before it creates anything. In the platform, open the settings menu, go to Account Information and Setup, then Licensing, and check the Molecule line. You need at least one free.

I learned this the hard way. My first attempt ran all the way through downloading the Java runtime and the Atom and Molecule files, and then failed at "Retrieving Container ID" with a message saying the account had already reached its Molecule limit. The installer rolled everything back cleanly, but I'd lost about an hour. The licences were tied up by older test Molecules still registered in the account. So check this first. If you're at the limit, remove any unused Molecules you own, or use an account that has spare capacity.

Make sure you're in the right account

If your Boomi user can access more than one account, check which one is selected before you download anything. The installer file is the same for every account, but the token you paste in during installation ties the Molecule to a specific account. If you grab a token from the wrong account, just switch accounts, generate a fresh token there, and reuse the same installer file.

Create an environment

A Molecule has to belong to a Boomi environment. In Manage, then Runtime Management, create one with the New button if you don't already have a suitable test or dev environment. Give it a clear name and set its classification to Test.

Understand the cost

Nothing here is free tier. Two t3.medium instances cost roughly USD 0.08 per hour combined while they're running. EFS is billed by the amount of data you store, around USD 0.30 per GB-month, and a Molecule installation is only a few hundred megabytes, so the storage cost is small. The section on pausing and resuming covers how to avoid paying for compute you aren't using.

Part 1: Build the AWS infrastructure

Everything in this part happens in the AWS Console in your browser. Nothing gets typed into a terminal yet.

Create the shared file system

Search for EFS in the AWS Console and choose Create file system. Give it a name, pick your default VPC, and click Create.

When the file system opens, you need two things from the top of the page. The first is the file system ID, which looks like fs-0123456789abcdef0. The second is the DNS name, shown in a copyable box on the right. It looks like fs-0123456789abcdef0.efs.us-east-1.amazonaws.com. Copy the DNS name exactly, because you'll paste it into a command later.

Open the Network tab. There's one mount target per Availability Zone, and each one starts in the Creating state. Wait until every row says Available before you try to mount anything. If you don't, the mount command just hangs.

You don't need the mount target IDs, the network interface IDs, or the individual IP addresses in that table. The DNS name works from any subnet and resolves to the right mount target automatically.

Create the security group

A security group is the firewall for your instances. I used one group for both nodes and the EFS mount targets, which keeps the rules simple.

Go to EC2, then Security Groups, then Create security group. Give it a name. It can't be changed later, so pick something you'll recognize. Add a description, which can be anything as long as it isn't blank. The form won't submit without one, and the error message is easy to miss among the other red boxes. Pick the same default VPC as EFS.

Add these inbound rules. Leave the outbound rules at their defaults. "Allow all outbound" is exactly what the nodes need, so they can reach the Boomi platform, download packages, and connect to EFS.

Type	Port	Source	Purpose
SSH	22	My IP	Terminal access from your machine
Custom TCP	9090	My IP	Calling the web server from your machine (optional)
All traffic	All	This security group	Node-to-node cluster traffic
NFS	2049	This security group	Nodes connecting to EFS

A security group describes traffic arriving at a machine, so node 1 talking to node 2 needs node 2 to accept it. Because both nodes are in the same group, one rule that says "allow traffic from members of this group" covers both directions. The EFS mount targets are in the same group, so the NFS rule lets both nodes reach them.

Common mistake: adding the self-referencing rules while you create the group. The rules whose source is "this security group" can't be filled in until the group exists, so the form will complain that a CIDR block, security group ID, or prefix list is needed. Do it in two rounds. Create the group with just the SSH and 9090 rules. Then open it, choose Edit inbound rules, add the other two rows, and in each Source box type the group's name and pick it from the list. It shows up as a blue tag with its sg- ID.

Common mistake: typing the group name into the Description column. That column is a free-text label with no effect. The group reference has to go in the Source search box.

Attach the security group to the EFS mount targets

Back in EFS, open your file system, go to Network, and choose Manage. For every mount target, replace the default security group with the one you just made, then save. Without this, the servers will time out when they try to mount, because the default group doesn't allow NFS from them.

Launch two EC2 instances

Go to EC2, choose Launch Instance, and create the first node with these settings:

Name: node-1
AMI: Amazon Linux 2023. It's simple, well integrated with AWS, and uses yum and dnf.
Instance type: t3.medium (2 vCPU, 4 GB RAM). Boomi recommends at least 4 GB per node. A t3.small will run a demo but is marginal, and a t3.micro won't work.
Key pair: a key pair you already have the .pem file for. Use the same key for both nodes so SSH stays simple.
Network settings: select the existing security group you just built. Don't let the wizard create a new one, because the nodes have to be in your group.
Subnet: pick one and note which one. Both nodes need to be in the same subnet.

Launch a second instance the same way and call it node-2, putting it in the same subnet.

When both show Running, open each one and write down two addresses. The public IPv4 address is what you use for SSH from your laptop. It changes every time you stop and start the instance. The private IPv4 address is what the nodes use to talk to each other in the cluster, and it doesn't change.

If you don't want to copy the public IP every time, you can allocate an Elastic IP and attach it to each instance. It's free while attached to a running instance, but it costs a small amount per hour while the instance is stopped, so it's optional for a learning setup.

Part 2: Connect to the nodes and mount the shared disk

From here on you'll be working in two kinds of terminal, and mixing them up caused more errors for me than anything else. Check the prompt before you paste a command.

Prompt looks like	Where you are	What goes here
`yourname@your-laptop ~ %`	Your laptop	`ssh` to connect, `scp` to copy files up
`[ec2-user@ip-<NODE_PRIVATE_IP_DASHED> ~]$`	Node 1	Everything that runs on the server
`[ec2-user@ip-<NODE_PRIVATE_IP_DASHED> ~]$`	Node 2	Everything that runs on the server

The last few digits of the private IP tell you which node you're on.

Connect to both nodes

Open two terminal tabs on your laptop, and in each one run ssh with the public IP of one node. The -i option names the key file you downloaded when you created the key pair. ec2-user is the default login on Amazon Linux. The first time you connect to a new server, SSH will ask whether to trust its fingerprint. Type yes.

Common mistake: using the private IP for SSH. You'll get Connection reset by peer. Private IPs only exist inside AWS, so your laptop can't reach them. Use the public IP for SSH and save the private IP for the cluster setup later.

Common mistake: SSH times out because your IP has changed. The SSH rule is set to My IP, and that's a snapshot. If your laptop's public IP has changed since you created the rule, SSH will time out. Open the security group, edit the inbound rules, and set the SSH row's source to My IP again. AWS fills in your current address. Do the same for the 9090 row.

Common mistake: running ssh from inside a server. I had a tab still logged into a node from the day before. When I ran the ssh command there, it failed with a "not accessible" warning, because the key file only exists on my laptop. Check the prompt. If it says ec2-user@ip-..., you're already on a server. Press Ctrl+C, or type exit, and run the command from your laptop.

If things get muddled and you can't tell which tab is which node, quit the terminal app, reopen it, and connect to node 1 in the first tab and node 2 in the second. Then check each prompt. It takes thirty seconds and saves a lot of confusion.

Install Java and the NFS client on both nodes

On each node, run:

sudo yum update -y
sudo yum install java-17-amazon-corretto nfs-utils -y

yum update brings the operating system up to date. java-17-amazon-corretto is Amazon's build of OpenJDK 17. The Boomi installer bundles its own Java runtime, but having a system Java around is useful for troubleshooting. nfs-utils provides the NFS mount helper EFS needs. Without it, the mount fails with "unknown filesystem type."

Mount EFS on both nodes

On each node, create a folder and mount the file system into it:

sudo mkdir -p /mnt/boomi
sudo mount -t nfs4 -o nfsvers=4.1 <EFS_DNS_NAME>:/ /mnt/boomi
df -h /mnt/boomi

mkdir -p creates the folder and doesn't complain if it already exists. The mount command attaches the root of the EFS file system to that folder over NFS 4.1, which is the version EFS supports. df -h shows what's mounted. A successful mount shows a line ending in /mnt/boomi, with a size of 8.0E. That's EFS reporting a huge nominal size, because it grows as you use it.

Replace <EFS_DNS_NAME> with the DNS name from the EFS console, exactly as it appears there.

Common mistake: a mistyped EFS DNS name. I got Failed to resolve server ...: Name or service not known because the .efs part was missing from the name, and I'd also copied backticks from a chat message along with the ID. The address has to be exactly <file-system-id>.efs.<region>.amazonaws.com. Copy it from the console instead of typing it.

If the mount hangs for a minute and then says Connection timed out, one of two things is wrong. Either the mount targets aren't Available yet, or you haven't attached the security group to them.

Next, make the mount permanent so it comes back after a reboot or a stop and start. Then give ec2-user ownership of the shared folder:

echo "<EFS_DNS_NAME>:/ /mnt/boomi nfs4 nfsvers=4.1,_netdev 0 0" | sudo tee -a /etc/fstab
sudo chown ec2-user:ec2-user /mnt/boomi

/etc/fstab is the list of file systems Linux mounts at boot. tee -a appends the line with root permission. The _netdev flag tells the boot process to wait for networking before trying this mount. The chown makes the shared folder writable by the user that will run the installer and the Molecule.

Using the same user on every node matters. Files written to EFS by node 1 have to be readable and writable by node 2. NFS identifies users by numeric ID, and ec2-user has the same ID on every Amazon Linux instance, so using that one user everywhere avoids a whole class of permission problems.

To prove both nodes see the same disk, run touch /mnt/boomi/hello on node 1, then ls /mnt/boomi on node 2. You should see hello. Delete it afterwards with rm /mnt/boomi/hello.

Create the local assets folder on node 2

The installer will ask for a folder on each node's local disk, where per-node working files and the Java runtime are kept for speed. Node 1 creates it automatically during installation, but node 2 never runs the installer, so create it by hand:

mkdir -p /home/ec2-user/boomi_local

The path is saved in the shared configuration, so it has to be identical on every node.

Part 3: Get the installer and a token onto node 1

Download the Molecule installer

In the Boomi platform, check that you're in the right account, then go to Manage, then Atom Management, and click New. Choose Molecule, then Local, then Linux 64-bit, and download the file. It's called molecule_install64.sh.

Copy the installer to node 1

Run this from your laptop, not from a server:

scp -i ~/Downloads/<KEY_FILE>.pem ~/Downloads/molecule_install64.sh ec2-user@<NODE_1_PUBLIC_IP>:~/

scp copies a file over SSH. The first path is the local file. The second is user@host:destination, and :~/ means your home folder on the server. A successful copy ends with a progress line at 100%.

Common mistake: running scp on the server. If you paste the command into the node's terminal, it can't find the file, because the file is on your laptop. Also make sure the destination has the trailing :~/, or the copy won't go where you expect.

Then, on node 1, confirm the file arrived and make it executable:

ls -la ~/molecule_install64.sh
chmod u+x molecule_install64.sh

chmod u+x gives the file's owner permission to run it. Downloaded scripts usually arrive without that permission.

Generate a token right before you install

On the same Atom Management screen, under Security Options, click Generate Token. Tokens expire quickly, often within thirty minutes, so generate it just before you run the installer. Paste it only into the installer prompt, and never into a chat, a document, or a ticket.

An installer token is a credential for your Boomi account. If one has ever been pasted somewhere it shouldn't be, generate a new one.

Part 4: Run the Molecule installer

On node 1 only, create the local folder and run the installer:

mkdir -p /home/ec2-user/boomi_local
./molecule_install64.sh

The script first looks for Java, downloads a runtime from the Boomi platform if it needs one (about 190 MB), and then starts the interactive installer in the terminal. You'll see some WARNING: An illegal reflective access operation has occurred lines. Those are harmless notices about an older installer running on a newer Java. Don't interrupt the install because of them.

Answer the prompts

Here's every prompt in order, with the answer I used. Replace the names with your own.

Prompt	Answer	What it means
This will install a Molecule on your computer. OK [o, Enter], Cancel [c]	Enter	Confirms you want to start
User Name and Password [1, Enter], Token [2]	`2`	Use a token instead of typing your Boomi password on a server
Token []	Paste the token	The credential from Part 3
Molecule Name [ip-.ec2.internal]	`<YOUR_MOLECULE_NAME>`	The default is the server's hostname, so give it something meaningful
Use Proxy Settings? Yes [y], No [n, Enter]	`n`	An EC2 instance in a default VPC has direct internet access
Choose an Environment, followed by a numbered list	The number next to your environment	Attach it to a test or dev environment, not production
Choose an installation directory	`/mnt/boomi/Molecule_<YOUR_NAME>`	Must be on EFS. If it's on the local disk, node 2 will have nothing to start
Store runtime assets locally [1, Enter], use cluster shared storage [2]	`1`	Keeps temp files, libraries, and the Java runtime on each node's local disk, which is faster
Working Data Local Storage Directory (required) []	`/home/ec2-user/boomi_local`	The folder from earlier. Use the same path on every node
Local Temp Directory [/tmp]	Enter	`/tmp` is local to each node, so this default is fine
Create symlinks? Yes [y, Enter], No [n]	`y`	Adds the `atom` commands to your PATH
Choose the location to create symlinks [/usr/local/bin]	Enter	Accept the default
Summary screen, [Enter]	Enter	Starts the actual installation

A successful run ends with messages about downloading the JRE, unpacking it, downloading the Atom and Molecule files, retrieving the container ID, and attaching the container to your environment. The last line says the Molecule has been installed.

Don't start the Molecule yet. Part 5 has to happen first.

Mistakes I made at the prompts

These all come from misreading how the console installer works. The rule is simple: the installer only accepts the answers shown in the brackets.

Typing an email address or token at the "1 or 2" prompt. The installer asks for 1 or 2. I typed my email, then the email and token together. Each time, it just asked again. Type the digit.

Choosing option 1 when I meant to use a token. Typing 1 moved me into the username and password prompts, and there's no way back from there inside the installer. Press Ctrl+C, run the installer again, and answer 2. Nothing has been installed at that point, so it's safe.

Typing the environment name or ID instead of its number. The environment list wants the number in brackets. The installer kept reprinting the list while I tried the name and then the GUID.

Typing y or yes at a [1, Enter] or [2] prompt. The asset-storage question offers 1 and 2, not y and n. Both y and yes were rejected before I typed 1.

Pressing Enter on a prompt with empty brackets. The Working Data Local Storage Directory (required) [] prompt has no default. Pressing Enter gave me "is required" and sent me back to the previous question. Type the path.

Accepting the default installation directory. The default is under /home/ec2-user, on node 1's local disk. A Molecule installed there works on node 1 and is invisible to node 2. The installation directory has to be on the shared mount.

Next up

In Part 2 we make the two nodes find each other with unicast, deal with the cluster problems I ran into, and open the web server port. Part 2 is linked at the end of this post once it is live.