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
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.
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.
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
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:
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 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
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)
- 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
ROOTvalue. 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.
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'
If for some reason you can't fetch the file or something appears to be wrong, we recommend adding
-v flag to your
curl commands to see the exact error messages and status codes being
returned from the server