Spin Apps in Registries

Spin Registry Support

With Spin’s registry support, you can package and save your Spin application as an artifact in a registry like GitHub Container Registry (GHCR) or DockerHub and then run your Spin app from these registries.

Prerequisites

First, follow this guide to ensure you have the latest version of Spin installed (this tutorial refers to Spin 1.0 and above). You can check the Spin version using the following command:

$ spin --version

Publishing and Running Spin Applications Using Registries (Video)

The following video shows you how to push a Spin app to GHCR, and then run that artifact with Spin or with Docker. The video also contains additional information about signing and verifying your GHCR artifacts.

The rest of this page shows you how to use GHCR artifacts locally with Spin.

Set Up Your GHCR Instance

To use a GHCR instance, you need to set up authentication. Follow these steps to generate a personal access token and then use it to sign into your GHCR. You should see the following message to confirm your login attempt to GHCR was successful:

> Login Succeeded

Push a Spin App to GHCR

Let’s use this full-stack TypeScript and ReactJS Spin app to walk through this tutorial. If you have a Spin app already feel free to navigate to that directory and skip the step below.

Fork and clone the app GitHub repository:

$ git clone https://github.com/USERNAME/spin-react-fullstack.git

Now, switch to that directory and rebuild the application:

$ cd spin-react-fullstack
$ spin build

Now we’re ready to push the application. Run the spin registry push command to push your application to the registry: 

$ spin registry push ghcr.io/USERNAME/spin-react-fullstack:v1

Note: You can find more information on spin registry options and subcommands in the Spin CLI Reference documentation.

You now have a Spin application stored in your registry. You can see the artifact under packages in the GitHub UI.

Pull a Spin App From GHCR

Now that we’ve successfully pushed a Spin app, let’s see if we can pull it. To do so, run the following command: 

$ spin registry pull ghcr.io/USERNAME/spin-react-fullstack:v1

Run a Spin App From GHCR

Lastly, let’s run this Spin application:

$ spin up -f ghcr.io/USERNAME/spin-react-fullstack:v1

Deploy a Spin App from GHCR (or any registry)

You can deploy a Spin app from any registry such as GHCR or DockerHub using the CLI command spin deploy -f <remote-reference-here>

Note: You need a Fermyon Cloud account to deploy to. The remote-reference can be private, as long as you are authenticated locally to the registry in question, since the CLI will pull it down prior to publishing it to Cloud’s internal registry.

Conclusion

Congratulations on completing this tutorial! You have now successfully built, pushed, pulled, and run a Spin app using GHCR. Behind the scenes, Spin uses OCI artifacts project to distribute Spin apps across container registries. To learn more about how this feature works, take a look at our proposal and the implementation.

Next Steps

  • If you’re interested in shaping how registry support will look in the next version, please share your thoughts in our Discord community