Deploying your Application

Prerequisites

To start an actor on Cosmonic, the actor must be a signed module, with claims information attached. Actors are automatically signed as part of cosmo build. For more information, see the previous page.

info

Hint: you can always check if an OCI reference is publicly accessible by inspecting its claims. You can also see what capabilities the actor declares, so you know exactly what the actor is allowed to do.

bash
cosmo inspect wasmcloud.azurecr.io/echo:0.3.8

bash
cosmo inspect wasmcloud.azurecr.io/echo:0.3.8

Deploying a Signed Module

Once your actor is signed, there are two ways you can deploy it:

Cosmo Launch

The easiest and quickest way to deploy an actor is with launch command. cosmo launch will check for a signed actor module in the target directory and start it on a local wasmCloud host connected to your super constellation.

caution

Since cosmo launch starts actors on a local wasmCloud host, if you stop this host, all actors (and providers) running on it will be terminated. If you need your application to continue running independent of your local system, consider starting your actors on a Cosmonic-managed host from a public OCI registry. You can refer to the other set of instructions above for how to upload your actor to a public GitHub registry.

Public GitHub Registry

You can start any signed actor that is hosted as an artifact in a publicly accessible OCI registry. An easy way to publish an actor as an artifact to GitHub is via the GitHub actions automatically included with wasmCloud's project templates.

Generating a Personal Access Token

In order to push an actor to your GitHub Packages repository, or for our included Actions to do so, you must generate a Personal Access Token (PAT). This is an alternative password for your GitHub username that has restricted permissions for specific operations.

To create a personal access token, follow the guide in the GitHub Documentation. The only scope that you need to give this token is the write:packages scope, as shown below:

Security Warning

This personal access token is a secret and should not be shared with others.

Manually Pushing a Signed Actor

If you have an actor project that was not generated with cosmo new, you can manually push any signed wasmCloud actor to GitHub Packages. Signed actors come from running cosmo build inside of an actor project.

Hint

You can always check if an actor is signed by inspecting its claims. You can also see what capabilities the actor declares, so you know exactly what the actor is allowed to do.

bash
cosmo inspect path/to/actor_s.wasm

bash
cosmo inspect path/to/actor_s.wasm

If you're able to inspect the claims like above, you're able to push the actor to GitHub Packages and start it from Cosmonic.

Unix

If you're using a Unix system, simply export your GitHub username and personal access token for authentication with GitHub Packages, and then use cosmo reg push to push your actor. The following example is pushing an actor named hello, version 0.1.0.

bash
export COSMO_REG_USER=<your_github_username>
export COSMO_REG_PASSWORD=<your_gitub_personal_access_token>
cosmo reg push ghcr.io/$COSMO_REG_USER/hello:0.1.0 build/hello_s.wasm

bash
export COSMO_REG_USER=<your_github_username>
export COSMO_REG_PASSWORD=<your_gitub_personal_access_token>
cosmo reg push ghcr.io/$COSMO_REG_USER/hello:0.1.0 build/hello_s.wasm

Windows

If you're using a Windows system, simply export your GitHub username and personal access token for authentication with GitHub Packages, and then use cosmo reg push to push your actor. The following example is pushing an actor named hello, version 0.1.0.

powershell
$env:COSMO_REG_USER = <your_github_username>
$env:COSMO_REG_PASSWORD = <your_gitub_personal_access_token>
cosmo reg push ghcr.io/$env:COSMO_REG_USER/hello:0.1.0 build/hello_s.wasm

powershell
$env:COSMO_REG_USER = <your_github_username>
$env:COSMO_REG_PASSWORD = <your_gitub_personal_access_token>
cosmo reg push ghcr.io/$env:COSMO_REG_USER/hello:0.1.0 build/hello_s.wasm

Now, you can navigate to your GitHub profile and access the Packages tab to see your actor. By default this is private and requires authentication to access, though it's simple to make this publicly accessible. Simply navigate to your package, find Package Settings in the right menu bar, and at the bottom of the page set the package visibility to public. Then, you're ready to use the Logic View to start your actor!

Continuous Integration with a GitHub Repository

Pushing an actor manually is nice for one-time pushes, but it's much more useful to manage actors using a version control system and deploy with an automatic continuous integration tool. Due to the ubiquity, ease-of-use, and free public availability, we provide GitHub Actions in our actor projects that can manage building, signing, and releasing actors for you.

When you generate a new actor project with cosmo new actor, two templates are included for you: build.yml and release.yml. The build action will build and run format and linting tests when you push to GitHub, and the release script will build, sign, push your actor to GitHub packages, and create a GitHub release with information about your actor.

Generating an Actor Project

To generate a Rust actor from the hello template, run:

bash
cosmo new actor --template hello hello

bash
cosmo new actor --template hello hello

This will create a new actor that responds to HTTP requests with "Hello, World", or "Hello, {name}" if you provide a query string with a name.

Pushing your Code to GitHub

If you change directory into the hello folder, cosmo already initialized it as a git repository for you, you just need to provide a repository URL and push the code there. Follow the GitHub quickstart guide to create a repository. Once the repository is created, run the following commands, replacing the repository URL with your own:

bash
git add .
git commit -m "first commit"
git remote add origin <your_repository_url>
git push -u origin main

bash
git add .
git commit -m "first commit"
git remote add origin <your_repository_url>
git push -u origin main

This will add all of your local files, commit them as a "first commit", and push them to your GitHub repository.

Adding Repository Secrets

In order to sign and release your actor, we need to provide three pieces of information in Action Secrets, located under the repository Settings > Secrets > Actions.

Name	Description
WASH_ISSUER_KEY	The 58 character issuer, or account, key for this actor. Can be found under $HOME/.wash/keys with the form of <your_username>_account.nk. Copy the contents of this file, a 58 character NKey starting with SA, into the value section. This file is generated when you run cosmo build. Copy the *_Seed* value from the file.
WASH_SUBJECT_KEY	The 58 character subject, or module, key for this actor. Can be found under $HOME/.wash/keys with the form of <your_actor>_module.nk. Copy the contents of this file, a 58 character NKey starting with SM, into the value section. This file is generated when you run cosmo build. Copy the *_Seed* value from the file.
WASMCLOUD_PAT	Your GitHub Personal Access Token with permission to write:packages. Should start with ghp_

Releasing your Actor

Back in your terminal, run the following command to create a tag for your repository for version 0.1.0 of your actor:

bash
git tag -a v0.1.0 -m "first actor release"
git push -u origin v0.1.0

bash
git tag -a v0.1.0 -m "first actor release"
git push -u origin v0.1.0

This will automatically kick off the release action. In a few minutes you should see a new release in your repository:

In the release, you can see public key information about who signed the actor, what the actor's identity is, the capabilities the actor uses, and most importantly, the OCI reference you can use to start the actor in Cosmonic.

Private GitHub Packages

By default, your GitHub package will be Private and Cosmonic won't be able to download it. The first time you release a new package, you have to click on the package in the repository sidebar, find Package Settings in the right menu bar, and at the bottom of the page set the package visibility to public.

Running your Actor in Cosmonic

As soon as you have a publicly accessible OCI Reference, you're ready to use the Logic View to launch your actor.

Hint

You can always check if an OCI reference is publicly accessible by inspecting its claims. You can also see what capabilities the actor declares, so you know exactly what the actor is allowed to do.

bash
cosmo inspect <oci_reference>

bash
cosmo inspect <oci_reference>