Trial

Synadia Platform is a bundled distribution of enterprise-grade components that augment the capabilities of NATS.io.

The current components include:

NATS - A high-performance connectivity technology for building scalable cloud-to-edge applications.
Control Plane - A web-based management interface for observing and monitoring NATS systems, managing NATS accounts and users, and managing, viewing, and sharing JetStream assets.
HTTP Gateway - An HTTP interface for interacting with key-value buckets, object stores, and general messaging over subjects.

For this trial, the goal is to spin up an isolated stack using Docker in order to evaluate the features of the platform.

If you run into any issues during your trial, reply to the trial email, use our contact form, or drop a message in the #synadia channel in the NATS.io Slack!

Prerequisites

Sign up here if you haven't already. You will receive an email with credentials to access the Synadia image registry. This provides access to OCI-compliant images (e.g. Docker).

Install Docker

If you don't have Docker installed, refer to the Get Docker documentation for instructions on how to install Docker Desktop or Docker Engine on your plaform.

An alternate option is Podman, which is a daemonless container engine that can be used as a drop-in replacement for Docker. If this is preferred, when following along with the commands below, replace docker with podman.

Using the credentials from the previous step, login to the Synadia image registry, following the prompts.

docker login registry.synadia.io

Clone the trial repository

The next step is to clone the platform-trial repository which contains the Docker Compose file and pre-defined configuration for the trial.

git clone https://github.com/synadia-io/platform-trial.git
cd platform-trial

Setup Control Plane and NATS

The first component to setup is Control Plane.

Start Control Plane

In your terminal, run the following command from the root of the repository:

docker compose up -d control-plane

The first time Control Plane starts, it will print out the administrative user credentials to the logs. It will look something like this:

*****************************************************************************
*** Welcome to Synadia Control Plane!
*** An admin user has been created.
*** Please change the password in the Profile section after logging in.
*** username: admin
*** password: 6v69rxr6LBfSSAc82yfgKXVM3e5dp4Lz
*****************************************************************************

To view the logs, run:

docker compose logs control-plane

Copy the generated username and password for the next step.

To facilitate the setup within Control Plane, review the interactive walkthrough as you progress.

Open a browser and navigate to http://localhost:8080. Enter the generated username and password in the previous step. You will be redirected to a page with a button Add System to connect your first NATS system.

Click Add System and enter the following information with the Create option chosen.

Name: trial
URL: nats://nats1:4222,nats://nats2:4222,nats://nats3:4222

In this example, the hostnames of the URL are the names of the NATS containers in the Docker Compose file.

Why all three URLs? This is generally a best practice when configuring an application connecting to NATS to provide multiple URLs. If one URL is specified and that server happens to be temporarily unavailable, the application will not be able to connect. By providing multiple URLs, the application can try each one until it successfully connects.

Leave Enable JetStream checked and click Save. You will be redirected to the NATS Settings page.

Configure NATS Settings

For Choose a platform..., select Docker. Copy the configuration in the section 2. Create a file named... and paste it into the file called shared.conf in the root of the trial repository. This configuration contains the generated operator and system account JWTs used for preloading in the NATS configuration.

Click Continue, then under Select NATS Connection Method, choose Connect Directly to NATS.

Start the NATS cluster

Run the following command to bring up the NATS cluster:

docker compose up -d nats1 nats2 nats3

Test the NATS connection

Back in Control Plane, click Test Connection. You should see a success message and click Submit.

Finally, click on the Overview tab to see the cluster visualization.

Setup HTTP Gateway

HTTP Gateway provides an HTTP interface for interacting with key-value buckets, object stores, and backend microservices. Although this is an optional component to setup, for environments where only an HTTP client is available, this can act as a bridge for those applications.

Like above, here is a interactive walkthrough for configuring the HTTP Gateway within Control Plane.

Create an account, user, and KV bucket

The HTTP gateway is a standalone component that utilizes a standard NATS connection. Additionally, it requires a key-value bucket to store state that it requires. It is recommended to create a dedicated account for the user and bucket.

On the trial system page, go to Accounts and add a new account called http-gateway. Click into the new account and click the Users tab and add a new user called http-gateway.

Click into the new user and click Get Connected and then Download Credentials. Save the file and rename it to http-gateway.creds and move it to the root of the trial repository.

Click on the JetStream tab and add a new KV bucket called tokens.

Enable HTTP Gateway

Back on the trial system page, click on the Settings page and under the HTTP Gateway section do the following:

Enable it
Account: choose http-gateway
Token Bucket: tokens
Access URL: http://localhost:8081

Click the Submit button at the top.

The access URL is the endpoint where the HTTP Gateway will be exposed through Docker Compose.

Start the HTTP Gateway

Run the following command to bring up the HTTP Gateway:

docker compose up -d http-gateway

Once started, you can go http://localhost:8081/api/ in your browser to see the API documentation.

Next Steps

You have successfully setup up Synadia Platform!

Head over to the getting started guide to learn more about the features of Control Plane and watch an intro video.