Fully document what is required, including the go template stuff

[diederikdehaas]

I initially started responding to #356 but it got so extensive, I figured I better create a separate issue for it.

So (very) related, but also document which go template variables need to be set? And which can be set/are available?
And warn and/or raise error when that's not done.

Take f.e. this one: {{- $image := or .image "debian.tgz" -}}

I recently learned that that isn't a yaml thing, but a go template thing.
I (now) know that image := "value" is a shorthand for variable declaration and assignment. But what does the $ do? And what does the or mean? I've learned about the dot in go templates, but where does .image come from?

Still not fully understanding how it works, I thought I'd just try it and see what happens (and learn through that).
So I created this base-image.yml file (following instructions from recipe.go IIUC):

$ cat base-image.yml 
---
architecture: arm64

actions:
  - action: debootstrap
    suite: sid
    components:
      - main
      - non-free-firmware
    mirror: http://deb.debian.org/debian
    variant: minbase

And then I tried to build the image:

diederik@debos-builder:~/dev/pine64$ debos --verbose base-image.yml
2023/08/21 22:31:16 Recipe '/home/diederik/dev/pine64/base-image.yml':
2023/08/21 22:31:16   Architecture: arm64
2023/08/21 22:31:16   Actions:
2023/08/21 22:31:16   - Action: debootstrap, Description: 
2023/08/21 22:31:16     Suite: sid
2023/08/21 22:31:16     Mirror: http://deb.debian.org/debian
2023/08/21 22:31:16     Variant: minbase
2023/08/21 22:31:16     KeyringPackage: 
2023/08/21 22:31:16     KeyringFile: 
2023/08/21 22:31:16     Certificate: 
2023/08/21 22:31:16     PrivateKey: 
2023/08/21 22:31:16     Components: [main non-free-firmware]
2023/08/21 22:31:16     MergedUsr: true
2023/08/21 22:31:16     CheckGpg: true
Running /debos --artifactdir /home/diederik/dev/pine64 /home/diederik/dev/pine64/base-image.yml using kvm backend
2023/08/21 20:31:29 ==== debootstrap ====
2023/08/21 20:31:29 Debootstrap | I: Retrieving InRelease
...
<rest of debootstrap run>
...
2023/08/21 20:34:12 Debootstrap (stage 2) | I: Base system installed successfully.
2023/08/21 22:34:14 ==== Recipe done ====
diederik@debos-builder:~/dev/pine64$ ls -lah
total 16K
drwxr-xr-x 3 diederik diederik 4.0K Aug 21 21:02 .
drwxr-xr-x 3 diederik diederik 4.0K Aug 21 16:38 ..
-rw-r--r-- 1 diederik diederik  190 Aug 21 21:02 base-image.yml

So everything went successful ... but I still don't have an image?!?

Some additional questions:

1. Where does it do the building before it writes it to an image file ... if that would have been defined?
2. How can I use apt-cacher-ng which runs in my network, but without it getting added to the image? I did specify HTTP_PROXY=<apt-cacher-ng-host:3142> but it appears it's not using it? At least I didn't see relevant network traffic with bmon on my apt-cacher-ng host or in acng-report.html

[diederikdehaas]

After changing my base-image.yml to the following:

---
{{- $image := or .image "debian.img" -}}

architecture: arm64

actions:
  - action: debootstrap
    suite: sid
    components:
      - main
      - non-free-firmware
    mirror: http://deb.debian.org/debian
    variant: minbase

I got the following:

diederik@debos-builder:~/dev/pine64$ debos --verbose base-image.yml 
2023/08/21 23:49:47 Recipe '/home/diederik/dev/pine64/base-image.yml':
2023/08/21 23:49:47   Architecture: 
2023/08/21 23:49:47   Actions:
2023/08/21 23:49:47   - Action: debootstrap, Description: 
2023/08/21 23:49:47     Suite: sid
2023/08/21 23:49:47     Mirror: http://deb.debian.org/debian
2023/08/21 23:49:47     Variant: minbase
2023/08/21 23:49:47     KeyringPackage: 
2023/08/21 23:49:47     KeyringFile: 
2023/08/21 23:49:47     Certificate: 
2023/08/21 23:49:47     PrivateKey: 
2023/08/21 23:49:47     Components: [main non-free-firmware]
2023/08/21 23:49:47     MergedUsr: true
2023/08/21 23:49:47     CheckGpg: true
2023/08/21 23:49:47 Recipe file must have 'architecture' property

Removing the first line (---) made it run ... but still no image ?!??

[diederikdehaas]

Example config did work and it appears that the pack action is critical. So I guess this is a PEBKAC issue

[obbardc]

right, in your example you don't use the $image variable.
you're missing a pack action to create a tarball of the root filesystem, or an image-partition action to create a partitioned image :-)