image.md

# Image build

## Requirements

- [Packer](https://packer.io): this is the tool that will automate all the steps of image creation
- [Ansible](https://docs.ansible.com/): this is the tool that will be used to provision the virtual machine (take a look at the [requirements.txt file](/requirements.txt) for exact Ansible requirements)
- [VMware OVF Tool](https://code.vmware.com/web/tool/4.4.0/ovf): this is required by Packer to export the image from the VMware Hypervisor
- A running and reachable VMware ESXi Hypervisor

## Prepare Packer file

Copy the example Packer file `packer/example.json`, for example to `packer/mymediaserver.json`, and edit the copied file.

These variable must be configured:

- `variables.name`: used to set the output filename and the machine hostname
- `variables.esx_*`: VMware hypervisor connection settings
- `variables.network_*`: used to pre-configure network settings, leave empty to ignore
- `variables.skyreach_*`: use either `system_key` or `activation_key` and leave the other empty

Then you need the groups that will be applied to the machine, for example for a MediaServer:

```json
{
  [...]
  "provisioners": [
    [...]
    {
      "type": "ansible",
      [...]
      "groups": [
        "msmonitor",
        "postgres",
        "mirismanager",
        "wowza",
        "celerity",
        "mediaserver",
        "mediaimport"
      ]
    }
  ]
}
```

For a worker:

```json
{
  [...]
  "provisioners": [
    [...]
    {
      "type": "ansible",
      [...]
      "groups": [
        "mediaworker"
      ]
    }
  ]
}
```

You can also pass additional variables to ansible in `provisionners['1'].extra_arguments`.

## Build image

Check that the Packer file is valid (the hypervisor must be reachable):

```
make image-validate build=packer/mymediaserver.json
```

Build the OVA:

```sh
make image build=packer/mymediaserver.json
```

## Troubleshoot

### Hypervisor version incompatibility

If the produced OVA is not compatible with the hypervisor, try to change the "VM compatibility mode" by changing the value of `version` option.

More infromation:

- <https://packer.io/docs/builders/vmware-iso.html#version>

### Build failed

If a build fail at one of the Ansible steps, you can set to `true` the `keep_registred` and `skip_export` options, then connect to the VM on the hypervisor and do some diagnostics.

More information:

- <https://packer.io/docs/builders/vmware-iso.html#skip_export>
- <https://packer.io/docs/builders/vmware-iso.html#skip_compaction>