How to convert an entrypoint to a Pebble layer

This guide will show you how to take an existing Docker image entrypoint and convert it into a Pebble layer, aka the list of one or more services which is defined in rockcraft.yaml and then taken by the rock’s Pebble entrypoint.

Reference entrypoint

For this guide, the reference Docker image entrypoint will be NGINX. The official Debian-based NGINX image’s Dockerfile can be found here.

In summary, this Dockerfile is basically installing NGINX into the image and then defining the OCI entrypoint to be a custom shell script which parses the first argument given to it at container deployment time, and then configures and launches NGINX accordingly.

Design the Pebble services

A Pebble layer is composed of metadata, checks and services. The latter is present in rockcraft.yaml as a top-level field and it represents the services which are loaded by the Pebble entrypoint when deploying a rock.

Given the reference entrypoint, this guide’s goal is to create two services: one for nginx and another for nginx-debug. The following services snippet does just that:

    override: replace
    startup: disabled
    command: nginx [ -h ]
      TZ: UTC
    on-failure: shutdown
    override: replace
    startup: disabled
    command: nginx-debug [ -h ]
      TZ: UTC
    on-failure: shutdown

This is defining two separate Pebble services which are disabled by default at startup, have the same environment variable, but are executed with different commands (nginx and nginx-debug).

Build the rock

Copy the above snippet and incorporate it into the rockcraft.yaml file which will be used to build your rock, as shown below:

name: custom-nginx-rock
base: "[email protected]"
version: latest
summary: An NGINX rock
description: |
    A rock equivalent of the official NGINX Docker image from Docker Hub.
license: Apache-2.0

  - type: apt
    key-id: 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
      - jammy
      - nginx
    priority: always

    plugin: nil
    overlay-script: |
      set -x
      useradd -R $CRAFT_OVERLAY -M -U -r nginx

    plugin: nil
      - nginx-user
      - nginx
      - tzdata

# Services to be loaded by the Pebble entrypoint
    override: replace
    startup: disabled
    command: nginx [ -h ]
      TZ: UTC
    on-failure: shutdown
    override: replace
    startup: disabled
    command: nginx-debug [ -h ]
      TZ: UTC
    on-failure: shutdown

This Rockcraft recipe is fully declarative, with the creation of the “nginx” user being the only scripted step.

To reproduce what the reference NGINX Dockerfile is doing, notice the use of package-repositories in this rockcraft.yaml file, allowing you to also make use of NGINX’s 3rd party package repository (even using the same GPG key ID as the one used in the Dockerfile).

NOTE: to add custom configuration files, you can use the dump plugin.

Now, build the final custom NGINX rock with:

rockcraft pack

You should see something like this:

Launching instance...
Retrieved base [email protected] for amd64
Extracted [email protected]
Refreshing repositories | (4.6s)
Package repositories installed
Executed: pull nginx-user
Executed: pull nginx
Executed: pull pebble
Executed: overlay nginx-user
Executed: overlay nginx
Executed: overlay pebble
Executed: build nginx-user
Executed: skip pull nginx-user (already ran)
Executed: skip overlay nginx-user (already ran)
Executed: skip build nginx-user (already ran)
Executed: stage nginx-user (required to build 'nginx')
Executed: build nginx
Executed: build pebble
Executed: skip stage nginx-user (already ran)
Executed: stage nginx
Executed: stage pebble
Executed: prime nginx-user
Executed: prime nginx
Executed: prime pebble
Executed parts lifecycle
Exported to OCI archive 'custom-nginx-rock_latest_amd64.rock'

Then copy the resulting rock (from the OCI archive format) to the Docker daemon via:

sudo rockcraft.skopeo --insecure-policy copy oci-archive:custom-nginx-rock_latest_amd64.rock docker-daemon:custom-nginx-rock:latest

And finally, run the container:

docker run -d --name nginx-pebble-service -p 8080:80 custom-nginx-rock:latest --args nginx -g 'daemon off;' \; start nginx

Notice the given command start nginx, as this is Pebble’s client syntax to let the Pebble daemon know that the nginx service defined in rockcraft.yaml (which is disabled by default) should be enabled at startup. Otherwise, the Pebble daemon would start without any NGINX service, although you could still later on ask for that service to be started (via something like docker exec <container-name> start nginx).

At this point, your container should be deployed and running the nginx service, and you should be able to see the NGINX landing page by accessing port 8080 on you localhost:

curl localhost:8080

For which you should see the following output:

<!DOCTYPE html>
<title>Welcome to nginx!</title>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href=""></a>.<br/>
Commercial support is available at
<a href=""></a>.</p>

<p><em>Thank you for using nginx.</em></p>