Local Filesystem

This document will guide you through everything you need in order to connect your constellation to a local filesystem on your machine, or any machine 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 Blobstore capability. The key value provider that you'll be running on a local wasmCloud host will be the blobstore-fs provider.

Why use a local filesystem?

The goal behind this sample is to show you how you can use your infrastructure to store your own data locally 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.

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

Open Beta

If you choose to run this provider on a Cosmonic-managed host, keep in mind that during the Open Beta, the filesystem is limited to 500 MB of storage.

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 Blob store capability contracts, it's easiest if you use the Blobby fileserver actor. We're going to run this actor and two capability providers that implement its two contracts, an HTTP Server and the Blobstore FS provider:

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/blobby:0.1.0, which you should copy/paste into 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)
  • Blobby Actor
• One locally run host
  • Blobstore FS 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:

• Blobby -> HTTP Server (Wormhole) provider. No values need to be supplied.
• Blobby -> Blobstore FS Provider
  • Supply /tmp for the ROOT value. You can also set this to any local filepath you desire

If you click on the newly drawn link definition line between the Blobby actor and the Blobstore FS provider, you should see the following in your detail panel:

Blobstore Link Definition

And you'll see the following after clicking on the link between the Blobby 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 Blobby actor
• An HTTP Server (wormhole) provider
• A Blobstore FS provider
• An open, unauthenticated wormhole

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.

At this point you can right click on the Access your wormhole link from the wormhole detail panel (click the wormhole in your constellation's logic view) and copy the link to your wormhole.

Once you have that link, please replace it in the examples below to run through the different operations you can do with the Blobby actor:

# Create a file with some content
$ echo 'Hello there!' > myfile.txt

# Upload the file to the fileserver
$ curl -H 'Content-Type: text/plain' 'https://hidden-emoji-5423.cosmonic.app/myfile.txt' --data-binary @myfile.txt

# Get the file back from the server
$ curl -v 'https://hidden-emoji-5423.cosmonic.app/myfile.txt'
Hello there!

# Update the file
$ echo 'General Kenobi!' >> myfile.txt
$ curl -H 'Content-Type: text/plain' 'https://hidden-emoji-5423.cosmonic.app/myfile.txt' --data-binary @myfile.txt

# Get the file again to see your updates
$ curl 'https://hidden-emoji-5423.cosmonic.app/myfile.txt'
Hello there!
General Kenobi!

# Delete the file
$ curl -X DELETE 'https://hidden-emoji-5423.cosmonic.app/myfile.txt'

# (Optional) See that the file doesn't exist anymore (you'll see the 404 in the wall of curl output)
$ curl -v 'https://hidden-emoji-5423.cosmonic.app/myfile.txt'

Debugging

If for some reason you can't fetch the file or something appears to be wrong, we recommend adding the -v flag to your curl commands to see the exact error messages and status codes being returned from the server