This document will guide you through everything you need in order to connect your constellation to a Redis database running locally on your machine, or anywhere within your private infrastructure. For this sample, you'll be creating a wormhole that connects to an actor bound to the HTTP Server capability and obviously to the Key-Value capability. The key value provider that you'll be running on a local wasmCloud host will be the Redis provider.
Why use Local Redis?
The goal behind this sample is to show you how you can use your infrastructure to host your Redis while still taking advantage of Cosmonic's publicly accessible wormholes and managed infrastructure for your actors. It illustrates one of the core benefits of Cosmonic: allowing you to stitch together all manner of disparate infrastructures and have them form a single, seamless topology accessible from anywhere.
There are only a couple of things you'll need in order to go through this sample. The first is that you'll need an active Cosmonic account which you can get by signing up here.
You will need a locally running Redis (or a protocol-compatible equivalent). The instructions for installing Redis vary greatly across operating systems and environments. The Redis getting started guide has instructions for all supported operating systems. If you're looking at using Redis cloud, then you'll want to follow the instructions for external Redis.
Make sure that in addition to the Redis server, you also install the Redis CLI. Depending on the OS, these may be separate packages. Before continuing, you'll want to ensure that your server is running and you have the CLI installed.
If Redis and the CLI are installed properly, you should be able to issue the following command with no errors (note that the quotes may vary by OS):
redis-cli keys '*'
The output here will vary depending on whether your reusing an existing Redis installation or starting fresh.
The next thing you're going to need is the cosmo CLI. With
cosmo installed, if you haven't done so already, you'll want to run
cosmo up in order to join
your super constellation. You should be able to view your
Cosmonic constellation from the application and see that you have a host running managed within
Cosmonic and a host running locally in whatever location from which you ran
|One Local and One Managed Host|
Running this Capability Provider
To start this capability provider on your local wasmCloud host (the one you launched via
cosmo up), first click the Launch Provider button on the Logic View of your constellation.
You will see a modal dialog that looks similar to this:
|Launch Provider Dialog|
Change the OCI Reference to the URL from the following badge:
Next, select Find Host and supply the following criteria, which will select the host running locally:
Click the button to find the host and select the host in the result list. If you do not see your
local wasmCloud host, go back over the instructions to make sure you've properly run
cosmo up. If
you see more than one host, just pick the first one in the list.
While you can start any actor that works with both an HTTP Server and the Key Value capability contracts, it's easiest if you use the key value counter. We're going to run this actor and two capability providers that implement its two contracts, an HTTP Server and the already-launched Redis key-value:
Starting an Actor
Simply click the Start Actor button on your canvas to launch the actor. The OCI reference for
this actor is
wasmcloud.azurecr.io/kvcounter:0.4.0 and should be present in the dropdown once you
click the OCI reference field. It doesn't matter which host you run it on, but for this sample we've
decided to run this actor within Cosmonic, so use Find Host to select a host with the
cosmonic_managed label set to
Starting the HTTP Server Provider (wormhole)
Next, you'll want to start the wormhole version of the HTTP Server provider, as shown in the
previous dialog. Make sure you change the OCI reference to
cosmonic.azurecr.io/httpserver_wormhole:0.5.1. Similar to the previous provider start, you're
going to want to find a host on which to launch this provider. This provider must be launched on a
Cosmonic host. If you specify
true as the criteria for finding a host, any of
those hosts will be able to run this provider.
At this point, you should have the following running in your constellation:
- At least one Cosmonic managed host
- HTTP Server (Wormhole)
- Key Value Counter Actor
- One locally run host
- Redis Key Value Provider
With all of this running, it's time to set link definitions and configure a wormhole.
Setting Link Definitions
Using the link definitions section of the user guide as a reference, you will want to create the following link definitions:
- Key Value Counter -> HTTP Server (Wormhole) provider. No values need to be supplied.
- Key Value Counter -> Redis Provider
URLvalue. If your local Redis installation is on a different port or IP, or requires authentication, you'll need to change that URL here.
If you click on the newly drawn link definition line between the Key Value Counter actor and the Redis provider, you should see the following in your detail panel:
|Redis Link Definition|
And you'll see the following after clicking on the link between the KVCounter actor and the HTTP Server - Wormhole provider:
|HTTP Wormhole Link Definition|
Creating a Wormhole
Follow the instructions in the user guide to create a new wormhole. The only option for the target actor should be the key value counter actor. This actor shows up in the list of possibilities specifically because it has a link definition bound to the HTTP Server (wormhole) provider. Actors will not appear as possible wormhole targets without that link.
Now your constellation should contain the following:
- A key-value counter actor
- An HTTP Server (wormhole) provider
- A Redis key-value provider
- An open, unauthenticated wormhole
At this point you can use the
Access your wormhole link from the wormhole detail panel (click the
wormhole in your constellation's logic view). Add a counter name to the end of the URL like
For example, accessing the "quiet sound" wormhole (
we see the JSON output from the counter (your wormhole URL will be different):
After you access this URL a couple more times by refreshing the browser tab, you can use the
redis-cli local command line to see that the data really is being stored locally, all while
securely allowing access via public wormhole. With the counter key of
testing, you can issue the
following Redis command in the CLI to obtain the current count:
127.0.0.1:6379> get counter::testing "22"
|Example Running on Logic View|
The preceding screenshot shows what this sample looks like on the logic view of a constellation. The only thing that should look different on your constellation is the friendly name of the wormhole.