Let's make sure you're set up to deploy Unison code to the Cloud and familiar with the basic workflow. In this exercise, you'll deploy a simple HTTP service that responds with a greeting message.

πŸ“š What we'll cover

  • Deploying an HTTP service to the Cloud
  • Named services versus service hashes
  • Log viewing in the Cloud admin panel

The HTTP service logic is technically implemented for you, but you'll still need to deploy it to the Cloud. πŸ˜‰

πŸ₯ Getting Started

If you haven't yet, make sure you've done the following:

Then enter ucm in your terminal to start Unison and authorize your account to run on the Cloud with the auth.login command:

.> auth.login

Great! Your UCM console is set up to deploy to Unison Cloud.

Create a repository for the cloud-start project and pull the latest release to retrieve the stubs and tests.

.> project.create-empty cloud-start
cloud-start/main> pull @unison/cloud-start/releases/latest

🚒 Deploying the service

You'll implement the ex1_quickstart.deploy function, which should deploy the service to the Cloud and return a URI to call it.

πŸ“ Instructions

To get started run the following command in the UCM:

cloud-start/main> edit exercises.ex1_quickstart.deploy

Implement ex1_quickstart.deploy to do the following:

  • Deploy the pre-made helloWorld.logic as an HTTP service with deployHttp
  • Create a name for the service with ServiceName.create
  • Assign the name to the service hash with ServiceName.assign
  • Provide a handler for the Cloud ability to interact with the Cloud

We'll discuss the details of these functions next. But remember, you can use the view command to inspect the implementation and signatures of these functions or the docs command to read their docs.

Check out the HTTP service function we'll be deploying. Unison HTTP services are functions with the basic form HttpRequest -> HttpResponse. Our service is helloWorld.logic, which responds to the path /:name.

helloWorld.logic : HttpRequest ->{Exception, Log} HttpResponse
helloWorld.logic = Route.run do
  use Text ++
  name = Route.route GET Parser.text
  info "request for greeting" [("name", name)]
  ok.text ("πŸ‘‹ hello " ++ name ++ "\n")

Start by shipping this service to the Cloud with deployHttp. Its first argument is an Environment where the service should be deployed and the second is the service logic itself.

deployHttp : Environment
            -> (HttpRequest -> {Config, [...], Scratch} HttpResponse)
            -> {Exception, Cloud} ServiceHash HttpRequest HttpResponse

The return type, ServiceHash, is a typed hash of the code being deployed. If you change the implementation of the service, you'll get a new hash, so ServiceHash uniquely identifies a service deployment.

For convenience, we've provided a helper function, exercises.env, to use as your environment value.

Next, create a name for your service with ServiceName.create. The ServiceName gives a human-readable, static name to multiple service deployments over time. In your deployment function, you should link your ServiceName to the hash returned by deployHttp with the ServiceName.assign function.

Finally, these functions all require the Cloud ability, since they describe interactions with Unison Cloud. Enclose all these functions with the Cloud.main handler. It should be the first line in your deployment function.

πŸ“ Remember, the view command can help you get the signatures of the functions mentioned above.

When you're done implementing ex1_quickstart.deploy, save your scratch file and update your codebase. Submit your solution for validation:

cloud-start/main> run submit.ex1_quickstart

πŸ“‹ Cloud admin panel

Once your service is deployed, you can view it in the Unison Cloud admin page at app.unison.cloud

You should see your service listed in the "Named Services" tab. Service logs are automatically collected and displayed in the activity tab for the service.

You can use a browser or CURL to call the URI returned by the deploy function since your service is now live! ⭐️