Copy page

Guides

Build/Test Environments with ROMs

This guide shows how to deploy a Go runtime that compiles ROM-provided code before execution. The base image contains a generic server and Go toolchain. Each ROM only contains a rom.go file, which the instance compiles into a Go plugin (.so) at startup.

This pattern is useful for build and test environments where runtime code changes frequently but the execution environment stays stable.

Prerequisites

1. Install the CLI: Use the unikraft CLI or the legacy kraft CLI. You need a BuildKit builder. The easiest way is via Docker. Alternatively, set up and use BuildKit directly, see the quick start.

   The unikraft CLI is the current standard, while kraft is the legacy version. Choose one of the CLIs below and only run the commands associated with it for the rest of this guide.

2. Clone the examples repository and cd into the examples/build-environments directory:

   Code
   git clone https://github.com/unikraft-cloud/examples
   cd examples/build-environments/

Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

Deployment Workflow

Package the base image

Package and push the base Go runtime image (see server.go for the runtime implementation):

The server in server.go loads /rom/rom.go, compiles it to /run/rom.so using go build -buildmode=plugin, and invokes Handler() from the plugin.

Create an instance template from the base image

Create a short-lived instance from the base image (without ROM attached). The server writes to /uk/libukp/template_instance and turns the instance into a template before serving requests (see /platform/instances#instance-templates):

The output shows the instance details:

If you are fast enough, you can list information about the instance by running:

This instance is short-lived, since right before the server starts, it triggers a conversion into a template. To check the template is ready, run:

Package the ROMs

Each ROM contains a Go function implementation (see rom1/fs/rom.go and rom2/fs/rom.go).

Create instances from the template with different ROMs attached

Create an instance with the first ROM:

The instance will compile the ROM into a plugin on first start, which may take a few seconds. To check the progress, you can view the instance logs:

Create another instance with the second ROM:

The instance will compile the ROM into a plugin on first start, which may take a few seconds. To check the progress, you can view the instance logs:

List the instances and note their FQDN values:

Test both instances:

Code
curl https://sparkling-dawn-syowlbtj.fra.unikraft.app
curl https://nameless-wood-gw7pbnls.fra.unikraft.app

Code
Bye, World!
Auf Wiedersehen!

Cleanup

Learn more

Use the --help option for detailed information on using Unikraft Cloud:

Or visit the CLI Reference or the legacy CLI Reference.