1. What you'll learn: Overview
Hello and welcome! If you've never interacted with a Solace event broker before, you're in the right place. In this introductory CodeLab, you'll learn how to:
- Setup a Solace Event broker, and/or start a PubSub Cloud service
- Login to the Broker Manager GUI
- Utilize test WebSockets applications to send and receive data using Publish-Subscribe, the fundamental communication pattern for event-driven applications
- Improve routing and filtering using topic hierarchies and wildcards
- Create a durable queue for Guaranteed Messaging
- Test Guaranteed messaging to ensure no message loss
- Enable Replay on the Solace broker, and test it
2. Prerequisites
In order to complete this CodeLab, you will need to get access to a Solace Event Broker. At minimum, you will need to have internet access and a browser to use Solace PubSub Cloud. To run the software broker, you'll need to have Docker, VirtualBox, VMWare Player, or another similar technology available to you. More details in the next step.
3. Starting a Solace PubSub Event Broker
Let's get access to a Solace Event Broker!
Solace Cloud
Super easy, with no setup or hardware or anything required. Solace as a Service! Point your browser to console.solace.cloud to sign up for a free account.
Enter your specifics, and get signed up for an account.
Once you are logged in, you should see something like this: 
In the Solace Cloud Console, click Cluster Manager in the left navigation 
Click Create Service (or the + button if you have existing services) 
Fill in the service configuration details:
- Name : Choose a concise name (e.g.,
ep-codelab) - Environment : Leave as Default
- Cloud : Choose your preferred cloud provider (AWS, Azure, or GCP)
- Region : Select a region closest to your location
- Broker Release : Leave as default (latest stable)
- Service Type : Select Developer (free tier)
Click Create Service
The service will take 3-5 minutes to provision Status will show as Creating...
Once complete, the broker details page will load 
Software Broker
There are multiple options on how to install/download/configure/run the Solace event broker:
- If you have Docker installed, this is probably the easist way. Simply copy this line into a terminal to pull the latest image from Docker Hub, and boot it:
docker run -d -p 8080:8080 -p 55555:55555 -p:8008:8008 -p:1883:1883 -p:8000:8000 -p:5672:5672 -p:9000:9000 -p:2222:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --name=solace solace/solace-pubsub-standard
- Other Docker options are here: https://docs.solace.com/Solace-SW-Broker-Set-Up/Docker-Containers/Set-Up-Docker-Container-Image.htm
- To run VirtualBox, VMWare, HyperV, and others: check out solace.com/downloads
- Lots of other software install options are here:
4. Log in to the Management GUI
Ok, now that we (are pretty sure we) have a Solace broker up and running, let's log in to it!
Solace Cloud Broker
Once your service is deployed and ready, simply click on it to go into it and look at some basic configuration information:
Notice some of the buttons across the top:
- The "Connect" tab shows you all the required connection information for your messaging pub/sub applications (e.g. host, username, password, etc.), which we'll need in later steps. The info can be grouped either by protocol or by programming language.
- At the top-right, there should be a button saying "Open Broker Manager". Click on that to go into the Manager GUI.
Installed Software Broker
If you've installed Solace on your local host (laptop or whatever), point your browser to http://localhost:8080. Or whatever IP address where it's running. Just remember to use port 8080 for the managment access. You should see a login screen like:
Login with credentials admin / admin. Once connected, you should presented with a screen to choose which Message VPN to use. You will only have one, the "default" VPN:
Click on that box!
5. Looking around the Broker Manager
Welcome to the Solace event broker management GUI! From this webapp, you'll be able to view configured and runtime information, create new queues, create usernames and profiles, and other various administrative tasks for the Solace broker.
On the left side of the screen are the main sections to navigate through:
- Message VPN: VPN-level stats and config (a Message VPN is a virtual partition of a single broker... one Solace broker can host multiple Message VPNs, and each VPN can have different authorization schemes and topic spaces; client/messaging application activity happens within the scope of a VPN)
- Clients: information about connected and configured client applications
- Queues: used for Guaranteed / persistent messaging
- Connectors: helpful wizards to connect to a variety of web services
- Access Control: where you create new client usernames, ACL profiles, and client profiles
- Replay: where you can enable replay, to allow the broker to send previous messages again
- NOTE: Solace brokers do not use replay for recovery of persistent data (like Kafka)... there is a more fine-grained approach in Solace where each individual message is ACKnowledged to the broker when the consumer application is done with it
- Try Me! this is where we will connect two WebSocket test applications
6. Try Me!
On the left menu, click the Try Me! button to load the two WebSocket test apps: a Publisher (left) and a Subscriber (right).
Click on the "Connect" button of both the Publisher and the Subscriber. The green "Connected" icon should light up. This creates two WebSocket connections from your browser using a JavaScript API into the Solace event broker. The two apps are going to talk to each other through the Solace broker, even though they are running on the same page.
Solace Cloud
Choose, "Solace Web Messaging" and copy the password. Back on the Try Me! tab, click the little right-arrow > next to the "Connect" button to open the dropdown list, and enter your password information, rest all should be correct by default. Then hit "Connect" and ensure you are connected.
Connected!
Once you are connected, hit the "Subscribe" button on the right to add a single topic subscription to the Subscriber application (currently try-me topic). On the left side, try Publishing some messages and ensure they go through.
Try changing the topic and see what happens. Try unsubscribing and see what happens. When using Direct messaging, subscribing clients must be online (and subscribed) in order to receive published messages.
7. Topic Hierarchies and Wildcards
Solace supports a hierarchical topic structure, which mean you can be very descriptive in defining your topic... use it to describe the contents/intent of your message payload data. No need to use flat, coarse-grained topic labels like other brokers. Check out this documenation and this video for more information:
Each and every message can be published to a unique topic, depending on the event metadata. Some examples of valid Solace topics are:
hello/world/solaceacme/taxi/rider/hailcity/train/1234/alert/stoppedmfg/plant42/inv/update/p12345667payme/debit/qr/bank01/f89a09-2b9c065a3/ok
Subscription Wildcards
Because published topics can be so variable and dynamic, subscribers can use wildcards to match a single subscription to multiple published topics. Solace supports two different types of wildcards:
*Single-level wildcard, 0-or-more chars, matches up to the next level/.- Can be used with a prefix e.g.:
abc*, but not a suffix.
- Can be used with a prefix e.g.:
>Multi-level wildcard, matches one-or-more levels.- Must occur at the end of the topic subscription.
Some examples of Solace topic subscriptions, and topics that they match:
hello/world/*- ✅
hello/world/aaron - ❌
hello/world - ❌
hello/world/solace/rules
- ✅
acme/taxi/rider/>- ✅
acme/taxi/rider/hail - ✅
acme/taxi/rider/dropoff/051.0283/-001.7281
- ✅
city/*/*/alert/>- ✅
city/train/01784/alert/new - ❌
city/fire/stn014/alert
- ✅
mfg/plant*/inv/update/>- ✅
mfg/plant/inv/update/all - ✅
mfg/plant42/inv/update/o-rings/med/shortage - ❌
mfg/123plant/inv/update/boo
- ✅
payme/debit/*/bank01/*/ok- ✅
payme/debit/dep/bank01/acct:12345/ok - ❌
payme/debit/qr/bank01/anything/fail
- ✅
You can read more about topic wildcard subscriptions here.
8. Creating a Queue for Guaranteed Delivery
To use Solace's Guaranteed delivery (aka persistent messaging) so that no messages can be lost, even during network disconnects or broker restarts, then we need a queue endpoint to hold onto the messages for the consumer while it might be offline.
On the left side of the Manager GUI, click on "Queues": 
Click the "+ Queue" to create a new queue: 
Give the queue a name, and hit "Create": 
Optionally configure some settings (e.g. max quota), but you can leave everything as-is for now. Hit "Apply": 
You have a new queue! 🎉
A Bit of Best Practices: Queue Subscriptions!
Now, Solace supports publishing directly to a queue, and many legacy point-to-point style applications still do this. But there are massive architectural benefits to using the Publish-Subscribe or pub/sub pattern. And for this, we will need to add a topic subscription to the queue, so it attracts messages with matching topics (just like the test WebSocket app was doing).
Click on the queue to go into its details: 
Click on the "Subscriptions" tab on the top row: 
Click on the "+ Subscription" to add a new subscription(s): 
Enter a new topic subscription, feel free to use wildcards: 
Add another one if you wish, queues can have multiple subscriptions: 
Click "Create" and that's it... your queue now has topic subscriptions to attract messages published on matching topics!
9. Persistent Pub/Sub Try Me!
Now that a queue is created for the consumer, we can test it out with the Try Me! test apps again. On the Try Me! tab, on right right side Subscriber, click the "Bind to endpoint to receive guaranteed messages" button: 
Enter the name of your queue, and hit "Start Consume": 
This will bind the Subscriber application to the queue, and any data that the queue receives will be send to the application.
Now you're ready to publish. On the Publisher side, change the topic to something that will match the (wildcarded?) subscription you added to the queue. Ensure that you have changed the "Delivery Mode" (aka quality of service) to Persistent: 
Hit "Publish" and make sure your messages appear on the other side. 
Now try disconnecting the Subscriber application, and publish a few more messages. Reconnect the subscriber and rebind to the queue and observe what happens.
For more information on Guaranteed messaging and queues, please refer to these links:
10. Enabling Message Replay
This will be left as an exercise to the reader. Once you turn it on, navigate back to the "Queues" tab, select your queue, and see what "Actions" you can find to perform.
Back on the Try Me! tab, even though the Subscriber has consumed and ACKnowledged all its Guaranteed messages, you can use Repaly to send the messages to it again. But recall: Solace does not use replay for recovery... if a subscriber application crashes after receiving a message but hasn't ACKnowledged it, the broker will resend the message when the subscriber reconnects.
For more information about Replay and/or acknowledging messages, check the following links:
11. Next Steps
This CodeLab has shown the very basics of application messaging using publish-subscribe and the Solace event broker. For next steps, please consider one of these other CodeLab tutorials:
- Exploring Solace Native APIs - The Basics
- How to Event-Enable your REST Architecture with Solace Event Broker
Thank you for your time. Please come find us on Solace Community to ask any questions!
