Deploying your Application
You can create applications on Cosmonic using the provided capability providers and your own actors. The only requirement for starting an actor is that the actor must be a signed module with claims information attached. 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 included in the cosmo CLI. 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.
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 for our wasmCloud shell (aka wash) to push an actor to your GitHub Packages repository (ghcr.io), 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.
Pushing a Signed Actor Manually
If you have an actor project that was not generated with wash new, you can push any signed wasmCloud actor to GitHub Packages. Signed actors come from running make inside of an actor project, or by running cargo build --release and using wash claims sign to sign the bare WebAssembly module.
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.
wash claims 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 wash to push your actor. The following example is pushing an actor named hello, version 0.1.0.
export WASH_REG_USER=<your_github_username>
export WASH_REG_PASSWORD=<your_gitub_personal_access_token>
wash reg push ghcr.io/$WASH_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 wash to push your actor. The following example is pushing an actor named hello, version 0.1.0.
$env:WASH_REG_USER = <your_github_username>
$env:WASH_REG_PASSWORD = <your_gitub_personal_access_token>
wash reg push ghcr.io/$env:WASH_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, however 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 automatically in our actor projects that can manage building, signing, and releasing actors for you.
When you generate a new actor project with wash new actor, two templates are automatically included for you: build.yml and release.yml. The build action will automatically 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 an actor project, you must have wash installed. Then, to generate a Rust actor from the hello template, run:
wash 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, wash 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. If you haven't used wash to build actors locally yet, you can generate this by running wash keys gen account and copying the *_Seed* value. |
| 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. If you haven't used wash to build actors locally yet, you can generate this by running wash keys gen module and copying the *_Seed* value. |
| 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 and 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.
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.
wash claims inspect <oci_reference>