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
  • Identifying a service by hash and by name
  • 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

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

ex1_quickstart.deploy should 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 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 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 value, so call it like exercises.env().

Your 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.create. 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.create "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.

With the Cloud.main handler in place, your deployment 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.create "hello-world"
  ServiceName.assign serviceName serviceHash

Remember to update your codebase after saving your scratch.u file.

Then submit your solution for validation:

cloud-start/main> run submit.ex1_quickstart

πŸ“‹ 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! ⭐️