Local Redis

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.

Prerequisites

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.

Installing Redis

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.

Cosmo CLI

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 cosmo up.

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:

Property	Value
stargate	true

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.

Example Usage

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 true.

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 cosmonic_managed, true as the criteria for finding a host, any of those hosts will be able to run this provider.

Configuration

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
  • Supply redis://127.0.0.1:6379 for the URL value. 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.

Operations

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 demo. For example, accessing the "quiet sound" wormhole (https://quiet-sound-9976.cosmonic.app/testing), we see the JSON output from the counter (your wormhole URL will be different):

{"counter": 22}

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.