Getting started

This page takes you from the AWS Marketplace listing to your first message: subscribe, launch, connect, then publish and receive on the broker.

You need: an AWS account with permission to subscribe to AWS Marketplace products, launch EC2 instances and use AWS Systems Manager.

1. Subscribe

Open the NATS listing in AWS Marketplace, choose View purchase options, review the terms and subscribe. When the subscription is confirmed, choose Launch your software.

2. Launch the instance

On the EC2 launch page:

1. Keep the instance type at t3.medium.
2. Under Configure storage, use an encrypted gp3 root volume of at least 16 GiB.
3. Under Network settings, allow no inbound traffic. If you also want SSH, allow port 22 from your administrative address range only.
4. Under Advanced details, choose an IAM instance profile that includes the AWS managed policy AmazonSSMManagedInstanceCore, so you can connect with Session Manager.
5. Choose Launch instance.

3. Connect

In the EC2 console, select the instance, choose Connect, then Session Manager, then Connect. Switch to the ubuntu user:

sudo -iu ubuntu

4. Wait for first boot

On first boot the instance creates its TLS certificates, users and configuration, then starts NATS:

cloud-init status --wait
systemctl is-active sushi-nats-core-firstboot nats-server
curl -s http://127.0.0.1:8222/healthz

The health check returns {"status":"ok"} when the broker is ready.

5. Run the walkthrough

bash /opt/sushi/docs/demo.sh

6. Publish and receive a message

The helper runs the nats CLI as one of the example users and reads that user's password for you. In one session, subscribe:

sudo /opt/sushi/bin/nats-as.sh subscriber sub 'sushi.pilot.>'

In a second session, publish:

sudo /opt/sushi/bin/nats-as.sh publisher pub sushi.pilot.sensor 'temp=21.5'

The subscriber prints the message. The helper stops each command after 20 seconds.

Connect your application

Setting	Value
URL	tls://127.0.0.1:4222
CA certificate	/usr/local/share/sushi/nats/ca.pem
User	publisher or subscriber, or a user you add
Password	the contents of /etc/nats/credentials/<user>.password (root only)

Keep passwords out of tickets, chat and screen recordings.

From your workstation, through Session Manager

The broker listens only on the instance. To reach it from your own machine without opening a port, forward it with Session Manager. You need the AWS CLI and the Session Manager plugin installed locally:

aws ssm start-session --target <instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["4222"],"localPortNumber":["4222"]}'

While the session is open, clients on your machine connect to tls://127.0.0.1:4222. Copy the public CA certificate from /usr/local/share/sushi/nats/ca.pem on the instance to your machine and point your client at it. The certificate is valid for 127.0.0.1, so host name verification passes.

To serve applications elsewhere in your VPC, see Reach NATS from your VPC.