Copy page

Concepts

Remote builds

By default, unikraft build builds an image on your machine and needs a local BuildKit or Docker. With the --remote flag, the remote build server builds the image and pushes it to the registry. Your machine only sends the project files.

For local builds, see images.

Build remotely

Add --remote and name the image to push with --output:

Code
unikraft build . --remote --output <my-org>/<image-name>:latest

Without a value, --remote uses the default remote build server, https://controlplane.unikraft.com. To use another one, see select the remote build server.

The CLI logs these messages in order:

• building remotely, with the address of the remote build server.
• created build, with the ID of the build.
• The progress of the build steps.
• pushed image, with the reference and the digest of the image.

The image is then ready to use:

Code
unikraft run --metro fra --image <my-org>/<image-name>:latest

Select the metro

The remote build server chooses the metro that the build runs in. To limit the choice, give one or more metros, by name or by the address of the metro's API:

Code
unikraft build . --remote --metro fra --output <my-org>/<image-name>:latest

--metro applies only together with --remote.

What a remote build uses

The input is the same as for a local build:

• A directory with a Kraftfile builds from the Kraftfile.
• A directory without a Kraftfile builds from its Dockerfile.
• A path to a Kraftfile or a Dockerfile builds from that file, with its directory as the build context.

The CLI doesn't upload an archive. The remote build server reads the files that it needs from your machine while the build runs. A .dockerignore file at the root of the project applies. Keep the CLI running until the build ends.

These flags work as in a local build:

--insecure doesn't apply to a remote build.

Registry logins come from your machine: the Docker configuration and the current profile. You don't need to log in to index.unikraft.io.

Kraftfile limits

A remote build doesn't support these parts of a Kraftfile yet:

• kernel or unikraft
• libraries
• volumes
• template
• A ROM with a Dockerfile source

The runtime must be an image in a registry.

Builders

A remote build runs on a builder. A builder is an instance with a cache volume in your own account. Builds on the same builder share its cache.

A builder scales to zero when it has no build to run, and starts again for the next build.

The first remote build creates a builder with the name default and the default sizes. The platform deletes the default builder and its cache after 7 days without a build. A builder with another name stays until you delete it.

To choose the sizes, create the builder before the first build:

Code
unikraft builder create --vcpus 4 --memory 8GiB --cache 50GiB

You don't need a flag to use the builder. unikraft build --remote always runs on the default builder:

Code
unikraft build . --remote --output <my-org>/<image-name>:latest

unikraft build can't select a builder with another name yet.

The unikraft builder commands manage builders:

Select the remote build server

You only need this section to use a remote build server other than the default.

unikraft build --remote takes the address of the remote build server from the first of these that has a value:

To set the address in a profile, add build_url to it in ~/.config/unikraft/config.yaml:

config.yaml
profiles:
  <profile-name>:
    build_url: https://build.example.com

Cancel a build

Press Ctrl+C to cancel a remote build. The CLI tells the remote build server to cancel the build and then exits with code 1.

Detached builds

A build from the CLI is an attached build. The remote build server reads the project from your machine, so the build stops when the CLI stops.

A detached build has all its sources in the request, as a public git repository or an HTTPS tarball. It runs without a connection to your machine. The CLI can't start a detached build yet. Start one with New build in the console.

Builds in the console

Remote builds from the CLI also appear in the console, on the Builds page of the organization. The CLI has no command to list builds or to read the logs of an earlier build, so use the console for that.

The page of a build shows:

• The status: waiting, running, succeeded, failed, or cancelled.
• The inputs, the settings, and the logs of the build.
• The pushed image, with Open the image and Create instance.
• Cancel for a build in progress, and delete for a finished one.

Deleting a build removes the build and its logs. The pushed image stays.

Troubleshooting

For all flags, see the unikraft build reference.