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.

Prerequisites

Sign up for the trial

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, and podman compose is configured properly, any reference to docker in the commands below can be replaced with podman.

Login to the image registry

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.

Login to Control Plane

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.

Add a 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.

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.

Create a user and account

Now, let's see how we can create a user and account within Control Plane. Control Plane leverages NATS' decentralized authentication model in order to support dynamically managing accounts and users.

Click Accounts and add a new account called trial. Click into the new account and click the Users tab and add a new user called trial.

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

Using the credentials, you can now connect to the NATS cluster using the nats CLI tool:

nats --creds trial.creds --server nats://localhost:4222 pub test "Hello, World!"

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.

It it a good practice to separate the accounts and users for different components to ensure proper access control and management.

Back on the Accounts page 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.

Next, click 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

Try out the HTTP Gateway

Now that it is running, we can download an HTTP Gateway token to try it out. We can do this by navigating back to our trial user we created earlier and clicking Get Connected. You will notice there is now an option for HTTP Gateway. Click Generate Token and copy it.

Within your terminal, set TOKEN variable so it can be referenced in the following commands (be sure to paste the token you copied):

TOKEN=nhg_M6YAsbwyF4jsRbkJ_GEWWL7NkEUUqhPtvaCbBwRKz2SNyLhs3t94pk7WdqHEV

Using curl, here is an example of creating a new KV bucket called users:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"max_bytes": 1048576, "history": 10}' \
    http://localhost:8081/v1/kvm/buckets/users

And then putting a key-value pair into the bucket:

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"color": "blue"}' \
  http://localhost:8081/v1/kv/users/john.doe

Check out the full API documentation in your browser: http://localhost:8081/api/

Next Steps

You have successfully set up Synadia Platform!

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

If you have any questions or feedback, please reach out to us at Synadia or in the #synadia channel in the NATS.io Slack!