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

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.