# Configuration

All the configuration for building image variants is defined by multiple
config files; the base configs for official Alpine Linux cloud images are in
the [`configs/`](configs/) directory.

We use [HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) for
configuration -- this primarily facilitates importing deeper configs from
other files, but also allows the extension/concatenation of arrays and maps
(which can be a useful feature for customization), and inline comments.

----
## Resolving Work Environment Configs and Scripts

If `work/configs/` and `work/scripts/` don't exist, the `build` script will
install the contents of the base [`configs/`](configs/) and [`scripts/`](scripts/)
directories, and overlay additional `configs/` and `scripts/` subdirectories
from `--custom` directories (if any).

Files cannot be installed over existing files, with one exception -- the
[`configs/images.conf`](configs/images.conf) same-directory symlink.  Because
the `build` script _always_ loads `work/configs/images.conf`, this is the hook
for "rolling your own" custom Alpine Linux cloud images.

The base [`configs/images.conf`](configs/images.conf) symlinks to
[`alpine.conf`](configs/images.conf), but this can be overridden using a
`--custom` directory containing a new `configs/images.conf` same-directory
symlink pointing to its custom top-level config.

For example, the configs and scripts in the [`overlays/testing/`](overlays/testing/)
directory can be resolved in a _clean_ work environment with...
```
./build configs --custom overlays/testing
```
This results in the `work/configs/images.conf` symlink to point to
`work/configs/alpine-testing.conf` instead of `work/configs/alpine.conf`.

If multiple directories are specified with `--custom`, they are applied in
the order given.

----
## Top-Level Config File

Examples of top-level config files are [`configs/alpine.conf`](configs/alpine.conf)
and [`overlays/testing/configs/alpine-testing.conf`](overlays/testing/configs/alpine-testing.conf).

There are three main blocks that need to exist (or be `import`ed into) the top
level HOCON configuration, and are merged in this exact order:

### `Default`

All image variant configs start with this block's contents as a starting point.
Arrays and maps can be appended by configs in `Dimensions` and `Mandatory`
blocks.

### `Dimensions`

The sub-blocks in `Dimensions` define the "dimensions" a variant config is
comprised of, and the different config values possible for that dimension.
The default [`alpine.conf`](configs/alpine.conf) defines the following
dimensional configs:

* `version` - Alpine Linux _x_._y_ (plus `edge`) versions
* `arch` - machine architectures, `x86_64` or `aarch64`
* `firmware` - supports launching via legacy BIOS or UEFI
* `bootstrap` - the system/scripts responsible for setting up an instance
  during its initial launch
* `cloud` - for specific cloud platforms

The specific dimensional configs for an image variant are merged in the order
that the dimensions are listed.

### `Mandatory`

After a variant's dimensional configs have been applied, this is the last block
that's merged to the image variant configuration.  This block is the ultimate
enforcer of any non-overrideable configuration across all variants, and can
also provide the last element to array config items.

----
## Dimensional Config Directives

Because a full cross-product across all dimensional configs may produce images
variants that are not viable (i.e. `aarch64` simply does not support legacy
`bios`), or may require further adjustments (i.e. the `aws` `aarch64` images
require an additional kernel module from `3.15` forward, which aren't available
in previous versions), we have two special directives which may appear in
dimensional configs.

### `EXCLUDE` array

This directive provides an array of dimensional config keys which are
incompatible with the current dimensional config.  For example,
[`configs/arch/aarch64.conf`](configs/arch/aarch64.conf) specifies...
```
# aarch64 is UEFI only
EXCLUDE = [bios]
```
...which indicates that any image variant that includes both `aarch64` (the
current dimensional config) and `bios` configuration should be skipped.

### `WHEN` block

This directive conditionally merges additional configuration ***IF*** the
image variant also includes a specific dimensional config key (or keys).  In
order to handle more complex situations, `WHEN` blocks may be nested.  For
example, [`configs/cloud/aws.conf`](configs/cloud/aws.conf) has...
```
WHEN {
  aarch64 {
    # new AWS aarch64 default...
    kernel_modules.gpio_pl061   = true
    initfs_features.gpio_pl061  = true
    WHEN {
      "3.14 3.13 3.12" {
        # ...but not supported for older versions
        kernel_modules.gpio_pl061   = false
        initfs_features.gpio_pl061  = false
      }
    }
  }
```
This configures AWS `aarch64` images to use the `gpio_pl061` kernel module in
order to cleanly shutdown/reboot instances from the web console, CLI, or SDK.
However, this module is unavailable on older Alpine versions.

Spaces in `WHEN` block keys serve as an "OR" operator; nested `WHEN` blocks
function as "AND" operators.

----
## Config Settings

**Scalar** values can be simply overridden in later configs.

**Array** and **map** settings in later configs are merged with the previous
values, _or entirely reset if it's first set to `null`_, for example...
```
some_array = [ thing ]
# [...]
some_array = null
some_array = [ other_thing ]
```

Mostly in order of appearance, as we walk through
[`configs/alpine.conf`](configs/alpine.conf) and the deeper configs it
imports...

### `project` string

This is a unique identifier for the whole collection of images being built.
For the official Alpine Linux cloud images, this is set to
`https://alpinelinux.org/cloud`.

When building custom images, you **MUST** override **AT LEAST** this setting to
avoid image import and publishing collisions.

### `name` array

The ultimate contents of this array contribute to the overall naming of the
resultant image.  Almost all dimensional configs will add to the `name` array,
with two notable exceptions: **version** configs' contribution to this array is
determined when `work/images.yaml` is resolved, and is set to the current
Alpine Linux release (_x.y.z_ or _YYYYMMDD_ for edge); also because
**cloud** images are isolated from each other, it's redundant to include that
in the image name.

### `description` array

Similar to the `name` array, the elements of this array contribute to the final
image description.  However, for the official Alpine configs, only the
**version** dimension adds to this array, via the same mechanism that sets the
revision for the `name` array.

### `motd` map

This setting controls the contents of what ultimately gets written into the
variant image's `/etc/motd` file.  Later configs can add additional messages,
replace existing contents, or remove them entirely (by setting the value to
`null`).

The `motd.version_notes` and `motd.release_notes` settings have slightly
different behavior:
* if the Alpine release (_x.y.z_) ends with `.0`, `release_notes` is dropped
  to avoid redundancy
* edge versions are technically not released, so both of these notes are
  dropped from `/etc/motd`
* otherwise, `version_notes` and `release_notes` are concatenated together as
  `release_notes` to avoid a blank line between them

### `scripts` array

These are the scripts that will be executed by Packer, in order, to do various
setup tasks inside a variant's image.  The `work/scripts/` directory contains
all scripts, including those that may have been added via `build --custom`.

### `script_dirs` array

Directories (under `work/scripts/`) that contain additional data that the
`scripts` will need.  Packer will copy these to the VM responsible for setting
up the variant image.

### `size` string

The size of the image disk, by default we use `1G` (1 GiB).  This disk may (or
may not) be further partitioned, based on other factors.

### `login` string

The image's primary login user, set to `alpine`.

### `repos` map

Defines the contents of the image's `/etc/apk/repositories` file.  The map's
key is the URL of the repo, and the value determines how that URL will be
represented in the `repositories` file...
| value | result |
|-|-|
| `null`  | make no reference to this repo |
| `false` | this repo is commented out (disabled) |
| `true`  | this repo is enabled for use |
| _tag_   | enable this repo with `@`_`tag`_ |

### `packages` map

Defines what APK packages to add/delete.  The map's key is the package
name, and the value determines whether (or not) to install/uninstall the
package...
| value | result |
|-|-|
| `null`               | don't add or delete |
| `false`              | explicitly delete |
| `true`               | add from default repos |
| _tag_                | add from `@`_`tag`_ repo |
| `--no-scripts`       | add with `--no-scripts` option |
| `--no-scripts` _tag_ | add from `@`_`tag`_ repo, with `--no-scripts` option |

### `services` map of maps

Defines what services are enabled/disabled at various runlevels.  The first
map's key is the runlevel, the second key is the service.  The service value
determines whether (or not) to enable/disable the service at that runlevel...
| value   | result |
|-|-|
| `null`  | don't enable or disable |
| `false` | explicitly disable |
| `true`  | explicitly enable |

### `kernel_modules` map

Defines what kernel modules are specified in the boot loader.  The key is the
kernel module, and the value determines whether or not it's in the final
list...
| value   | result |
|-|-|
| `null`  | skip |
| `false` | skip |
| `true`  | include |

### `kernel_options` map

Defines what kernel options are specified on the kernel command line.  The keys
are the kernel options, the value determines whether or not it's in the final
list...
| value   | result |
|-|-|
| `null`  | skip |
| `false` | skip |
| `true`  | include |

### `initfs_features` map

Defines what initfs features are included when making the image's initramfs
file.  The keys are the initfs features, and the values determine whether or
not they're included in the final list...
| value   | result |
|-|-|
| `null`  | skip |
| `false` | skip |
| `true`  | include |

### `qemu.machine_type` string

The QEMU machine type to use when building local images.  For x86_64, this is
set to `null`, for aarch64, we use `virt`.

### `qemu.args` list of lists

Additional QEMU arguments.  For x86_64, this is set to `null`; but aarch64
requires several additional arguments to start an operational VM.

### `qemu.firmware` string

The path to the QEMU firmware (installed in `work/firmware/`).  This is only
used when creating UEFI images.

### `bootloader` string

The bootloader to use, currently `extlinux` or `grub-efi`.

### `access` map

When images are published, this determines who has access to those images.
The key is the cloud account (or `PUBLIC`), and the value is whether or not
access is granted, `true` or `false`/`null`.

### `regions` map

Determines where images should be published.  The key is the region
identifier (or `ALL`), and the value is whether or not to publish to that
region, `true` or `false`/`null`.