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, pre-made HTTP service that responds with a greeting message.

📚 What we'll cover

  • Deploying an HTTP service to the Cloud
  • Identifying a service by hash and by name
  • Log viewing in the Cloud admin panel

🐥 Getting Started

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

You'll implement the ex1_quickstart.deploy function, which will 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

ex1_quickstart.deploy will do the following:

  • Deploy the pre-made helloWorld.logic as an HTTP service with deployHttp
  • Create a static name for the service with ServiceName.named
  • Assign the name to the deployed service with ServiceName.assign
  • Provide the Cloud.main handler for the Cloud ability, so the service can be run on the Cloud

We'll discuss the details of these functions next.

📦 Deploy an HTTP service

Unison HTTP services are functions with the basic form HttpRequest -> HttpResponse. Our pre-written 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")

The function which deploys an HTTP service to the Cloud is deployHttp.

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

Its first argument is an Environment, which is a way of grouping Cloud resources into a configuration environment for basic access management.

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.

Call the deployHttp function in the ex1_quickstart.deploy function.

For convenience, we've provided a helper function, exercises.env, to use as an environment value. It's a delayed computation, so call it like exercises.env().

Your deploy function should contain a line like this:

  serviceHash = deployHttp exercises.env() helloWorld.logic

🏷️ Assign the service a name

Next, create a name for your service with ServiceName.named. A ServiceName gives a human-readable, static name to multiple service deployments over time.

In your deployment function, link the ServiceName to the hash returned by deployHttp with the ServiceName.assign function.

  serviceName = ServiceName.named "hello-world"
  ServiceName.assign serviceName serviceHash

🌥️ Handle the Cloud ability

Finally, these functions require the Cloud ability, since they describe interactions with Unison Cloud infrastructure. Enclose all these functions with the Cloud.main handler:

Cloud.main : '{IO, Exception, Cloud} a -> '{IO, Exception} a

Cloud.main expects a delayed computation, so your function should start with Cloud.main do:

exercises.ex1_quickstart.deploy : '{IO, Exception} URI
exercises.ex1_quickstart.deploy = Cloud.main do
  [...]

With the Cloud.main handler in place, your deployment function is set up to ship the service ot the Cloud.

Remember to save your scratch file and update your codebase, then submit your solution for validation:

cloud-start/main> run submit.ex1_quickstart
Solution

Altogether, your ex1_quickstart.deploy function should look something like this:

exercises.ex1_quickstart.deploy : '{IO, Exception} URI
exercises.ex1_quickstart.deploy = Cloud.main do
  serviceHash = deployHttp exercises.env() ex1_quickstart.helloWorld.logic
  serviceName = ServiceName.named "hello-world"
  ServiceName.assign serviceName serviceHash

📋 Visit the 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! ⭐️