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. If you haven't built anything yet, you may want to check out our getting started guide
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.
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
- Public GitHub Registry
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 constellation.
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.
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:
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.
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.
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
- Windows
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.
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
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.
$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:
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:
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:
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.
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.
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.
cosmo inspect <oci_reference>