From c88c0f0e663d7a9f3484d04a39f4563cf269ca79 Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Sun, 1 Dec 2024 16:17:20 +0100 Subject: [PATCH 1/5] docs(action): print digest sha for use container Signed-off-by: AtomicFS --- action/container/container.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/action/container/container.go b/action/container/container.go index 6f29d261..bebc24c2 100644 --- a/action/container/container.go +++ b/action/container/container.go @@ -117,6 +117,11 @@ func Setup(ctx context.Context, client *dagger.Client, opts *SetupOpts, dockerfi // Pull docker container container = client.Container().From(opts.ContainerURL) + imageRef, _ := container.ImageRef(ctx) + slog.Info( + "Container information", + slog.String("Image reference", imageRef), + ) } else { // Use Dockerfile slog.Info("Container setup running in Dockerfile mode") From 52cf16ce1e85912c0c8dcb0238d3ff3ed579275d Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Sun, 1 Dec 2024 16:18:27 +0100 Subject: [PATCH 2/5] docs: add notes on offline usage Signed-off-by: AtomicFS --- .cspell.json | 1 + docs/src/SUMMARY.md | 1 + docs/src/firmware-action/offline_usage.md | 33 +++++++++++++++++++++++ 3 files changed, 35 insertions(+) create mode 100644 docs/src/firmware-action/offline_usage.md diff --git a/.cspell.json b/.cspell.json index d5cb1377..72f4f3ce 100644 --- a/.cspell.json +++ b/.cspell.json @@ -103,6 +103,7 @@ "libelf", "libncurses", "libnss", + "linuxboot", "logdir", "mainboard", "mainboarddir", diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 9f3ce574..4b621033 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -19,6 +19,7 @@ - [Local system](firmware-action/usage_local.md) - [GitHub CI](firmware-action/usage_github.md) - [Configuration](firmware-action/config.md) + - [Offline usage](firmware-action/offline_usage.md) - [Features](firmware-action/features.md) --- diff --git a/docs/src/firmware-action/offline_usage.md b/docs/src/firmware-action/offline_usage.md new file mode 100644 index 00000000..3880f377 --- /dev/null +++ b/docs/src/firmware-action/offline_usage.md @@ -0,0 +1,33 @@ +# Offline usage + +`firmware-action` under the hood uses [dagger](https://docs.dagger.io/) / docker. As such, the configuration contains entry `sdk_url` which specifies the docker image / container to use. + +```admonish example +~~~json +"sdk_url": "ghcr.io/9elements/firmware-action/coreboot_4.19:main" +~~~ +``` + +However, in this configuration `firmware-action` (or rather `dagger`) will always connect to the internet and download the manifest to see if a new container needs to be downloaded. This applies to all tags (`main`, `latest`, `v0.8.0`, and so on). + +If you need to use `firmware-action` offline, you have to first acquire the container. Either by running `firmware-action` at least once online, or by other means provided by docker. + +Then you need to change the `firmware-action` configuration to include the image reference (digest hash). + +```admonish example +~~~json +"sdk_url": "http://ghcr.io/9elements/firmware-action/coreboot_4.19:main@sha256:25b4f859e26f84a276fe0c4395a4f0c713f5b564679fbff51a621903712a695b" +~~~ +``` + +Digest hash can be found in the container hub. For `firmware-action` containers see [GitHub](https://github.com/orgs/9elements/packages?repo_name=firmware-action). + +It will also be displayed every time `firmware-action` is executed as `INFO` message near the start: +``` +[INFO ] Container information + - time: 2024-12-01T12:09:43.62620859+01:00 + - Image reference: ghcr.io/9elements/firmware-action/coreboot_4.19:main@sha256:25b4f859e26f84a276fe0c4395a4f0c713f5b564679fbff51a621903712a695b + - origin of this message: container.Setup +``` + +Simply copy-paste the digest (or image reference) into your configuration file and firmware-action will not connect to the internet to fetch a container if one matching is already present. From c5f60d3100c44ce0995d324423fdd8f0b5fe8c86 Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Sun, 1 Dec 2024 16:18:52 +0100 Subject: [PATCH 3/5] docs: add common troubleshooting steps Signed-off-by: AtomicFS --- docs/src/SUMMARY.md | 1 + docs/src/firmware-action/troubleshooting.md | 42 +++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 docs/src/firmware-action/troubleshooting.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 4b621033..4a187028 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -20,6 +20,7 @@ - [GitHub CI](firmware-action/usage_github.md) - [Configuration](firmware-action/config.md) - [Offline usage](firmware-action/offline_usage.md) + - [Troubleshooting](firmware-action/troubleshooting.md) - [Features](firmware-action/features.md) --- diff --git a/docs/src/firmware-action/troubleshooting.md b/docs/src/firmware-action/troubleshooting.md new file mode 100644 index 00000000..9a732441 --- /dev/null +++ b/docs/src/firmware-action/troubleshooting.md @@ -0,0 +1,42 @@ +# Troubleshooting common problems + +Many `firmware-action` errors and warnings come with suggestion on how to fix them. + +Other than that, here are some common problems and solutions. + + +```admonish tip +The first thing when troubleshooting is to look through the output for errors and warnings. Many of these messages come with a `suggestion` with instructions on possible solutions. + +For example a warning message: +~~~ +[WARN ] Git submodule seems to be uninitialized + - time: 2024-12-02T12:42:33.31416978+01:00 + - suggestion: run 'git submodule update --depth 0 --init --recursive --checkout' + - offending_submodule: coreboot-linuxboot-example/linux + - origin of this message: main.run +~~~ +``` + + +## Missing submodules / missing files + +The problem can manifest in multiple way, most commonly with error messages of missing files. +``` +make: *** BaseTools: No such file or directory. Stop. +``` + +Solution is to get all git submodules. +``` +git submodule update --depth 1 --init --recursive --checkout +``` + + +## Coreboot blob not found + +Blobs are copied into container separately from `input_files` and `input_dirs`, the path should point to files on your host. + + +## Dagger problems + +To troubleshoot dagger, please see [dagger documentation](https://docs.dagger.io/troubleshooting). From d61d0df750a9855d7408d1d780fa972f3ad499e8 Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Sun, 1 Dec 2024 21:26:43 +0100 Subject: [PATCH 4/5] docs: update dagger troubleshooting link Signed-off-by: AtomicFS --- action/container/container.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action/container/container.go b/action/container/container.go index bebc24c2..776b6dd2 100644 --- a/action/container/container.go +++ b/action/container/container.go @@ -186,7 +186,7 @@ func Setup(ctx context.Context, client *dagger.Client, opts *SetupOpts, dockerfi if errors.Is(err, context.DeadlineExceeded) { slog.Error( message, - slog.String("suggestion", "Your network configuration likely changed, try this: https://archive.docs.dagger.io/0.9/235290/troubleshooting/#dagger-pipeline-is-unable-to-resolve-host-names-after-network-configuration-changes"), + slog.String("suggestion", "Your network configuration likely changed, try this: https://docs.dagger.io/troubleshooting#dagger-is-unable-to-resolve-host-names-after-network-configuration-changes"), slog.Any("error", err), ) } From f3a4fccbce7cc5696e2316b962c938a9abee305a Mon Sep 17 00:00:00 2001 From: AtomicFS Date: Mon, 2 Dec 2024 12:51:47 +0100 Subject: [PATCH 5/5] docs: update git submodule update suggestion Signed-off-by: AtomicFS --- action/main.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action/main.go b/action/main.go index 179abfc2..540954b4 100644 --- a/action/main.go +++ b/action/main.go @@ -109,7 +109,7 @@ func run(ctx context.Context) error { patterSub := regexp.MustCompile(`^\-[\d\w]* `) slog.Warn( "Git submodule seems to be uninitialized", - slog.String("suggestion", "run 'git submodule update --init --recursive'"), + slog.String("suggestion", "run 'git submodule update --depth 0 --init --recursive --checkout'"), slog.String("offending_submodule", patterSub.ReplaceAllString(v, "")), ) }