Create a “Hello World” rock¶

Setup your environment¶

We recommend starting from a clean Ubuntu 22.04 installation. If you don’t have one available, you can create one using Multipass:

Is Multipass already installed and active? Check by running

snap services multipass

If you see the multipass service but it isn’t “active”, then you’ll need to run sudo snap start multipass. On the other hand, if you get an error saying snap "multipass" not found, then you must install Multipass:

sudo snap install multipass

Then you can create the VM with the following command:

multipass launch --disk 10G --name rock-dev 22.04

Finally, once the VM is up, open a shell into it:

multipass shell rock-dev

LXD will be required for building the rock. Make sure it is installed and initialised:

sudo snap install lxd
lxd init --auto

In order to create the rock, you’ll need to install Rockcraft:

sudo snap install rockcraft --classic

We’ll use Docker to run the rock. You can install it as a snap:

sudo snap install docker

Warning

There is a known connectivity issue with LXD and Docker. If you see a networking issue such as “A network related operation failed in a context of no network access”, make sure you apply one of the fixes suggested here.

Note that you’ll also need a text editor. You can either install one of your choice or simply use one of the already existing editors in your Ubuntu environment (like vi).

Project setup¶

Create a new directory and write the following into a text editor and save it as rockcraft.yaml:

# Metadata section

name: hello
summary: Hello World
description: The most basic example of a rock.
version: "latest"
license: Apache-2.0

base: bare
build-base: [email protected]
platforms:
  amd64:  # Make sure this value matches your computer's architecture

# Parts section

parts:
  hello:
    plugin: nil
    stage-packages:
      - hello

This file instructs Rockcraft to build a rock that only has the hello package (and its dependencies) inside. For more information about the parts section, check Part properties. The remaining YAML fields correspond to metadata that help define and describe the rock. For more information about all available fields check rockcraft.yaml.

Pack the rock with Rockcraft¶

To build the rock, run:

rockcraft pack

The output should look as follows:

Launching instance...
Retrieved base bare for amd64
Extracted bare:latest
Executed: pull hello
Executed: pull pebble
Executed: overlay hello
Executed: overlay pebble
Executed: build hello
Executed: build pebble
Executed: stage hello
Executed: stage pebble
Executed: prime hello
Executed: prime pebble
Executed parts lifecycle
Exported to OCI archive 'hello_latest_amd64.rock'

At the end of the process, a file named hello_latest_amd64.rock should be present in the current directory. That’s your rock, in oci-archive format (a tarball).

Run the rock in Docker¶

First, import the recently created rock into Docker:

sudo rockcraft.skopeo --insecure-policy copy oci-archive:hello_latest_amd64.rock docker-daemon:hello:latest

Now run the hello command from the rock:

docker run --rm hello:latest exec hello -t

Which should print:

hello, world