Docs/offline usage and troubleshooting

.cspell.json

@@ -103,6 +103,7 @@
     "libelf",
     "libncurses",
     "libnss",
+    "linuxboot",
     "logdir",
     "mainboard",
     "mainboarddir",

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")
@@ -181,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),
 			)
 		}

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, "")),
 			)
 		}

docs/src/SUMMARY.md

@@ -19,6 +19,8 @@
         - [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)
+    - [Troubleshooting](firmware-action/troubleshooting.md)
     - [Features](firmware-action/features.md)
 
 ---

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.

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).