work-vm/README.md

My generic work VM
==================

This repo contains a Vagrant configuration along with provisioning scripts which
can generate a blank, "work" VM. This VM must be installed on libvirt as recent
versions of Virtual Box don't really work for nested virtualization.

Features
--------

This VM is based on Debian 12. It includes the following features:
  * a pair of networks which can be used to host virtual machines,
  * a Bind DNS server that can serve a local zone as well as reverse zones for
    both networks, with a key that can be used to update the zones (e.g. using
    Terraform),
  * a local resolver configuration that will forward to either the local Bind
    server (for queries on the local zones) or to the host (for other queries),
  * Docker and libvirt,
  * a full XFCE environment with Firefox, Remmina, KeepassXC and LibreOffice
    installed,
  * various IaC tools: Packer, Terraform, Terragrunt and Ansible,
  * various programming languages:
    * Rust (installed using [Rustup](https://rustup.rs/)),
    * Golang (installed using [ASDF](https://asdf-vm.com)),
    * Node (installed using ASDF),
    * Java (installed using ASDF),
    * Python (installed using [pyenv](https://github.com/pyenv/pyenv)),
  * the ability to use [Chezmoi](https://www.chezmoi.io/) to import various dot
    files at provisioning time,
  * a semi-decent ZSH configuration (only installed if none is provided by the
    Chezmoi configuration) as well as my
    [Vim configuration](https://git.nocternity.net/tseeker-pub/heavim).

Installation
------------

Clone the repository:

```bash
git clone https://git.nocternity.net/tseeker-pub/work-vm my-local-name
```

If necessary, export some the following environment variables:

| Variable            | Default                     | Description                                                                                                           |
|--------------------:|:---------------------------:|-----------------------------------------------------------------------------------------------------------------------|
| `VM_CPU`            | 4                           | The amount of CPUs to allocate to the VM.                                                                             |
| `VM_MEMORY`         | 16384                       | The amount of memory to allocate (megabytes).                                                                         |
| `APT_PROXY`         | _empty_                     | APT proxy URL, if one is to be used.                                                                                  |
| `VM_LOCALE`         | `en_GB.UTF-8`               | Locale to configure on the VM.                                                                                        |
| `CHEZMOI_SOURCE`    | _empty_                     | Git URL to initialize Chezmoi from.                                                                                   |
| `VMNET_BACK_ADDR`   | 10.0.0.0                    | Address of the main "backend" network to be used for VMs inside the work VM. It will be interpreted as a /24 network. |
| `VMNET_FRONT_ADDR`  | 10.0.1.0                    | Address of the secondary, "service" network to be used for VMs. It will be interpreted as a /24.                      |
| `VMNET_DOMAIN`      | `envdev.test`               | Local domain name.                                                                                                    |
| `VMNET_BIND_KEY_ID` | `terraform.${VMNET_DOMAIN}` | Bind key identifier.                                                                                                  |
| `VMNET_BIND_KEY`    | _empty_                     | HMAC-SHA512 Bind key to import. A key will be generated automatically if this variable is empty.                      |

Then run Vagrant to provision the VM.

```bash
vagrant up
```

Known issues
------------

* The keyboard is configured to a French layout and there's no way to override
  it.
* The Chezmoi Git repo must be given using the full `ssh://git@...` URL if SSH
  is in use, otherwise initialization will fail (the script relies on the full
  URL syntax to extract the host name and fetch the host's key)
* The VM's Spice display is not configured properly due to a limitation of the
  `libvirt` plugin. It is necessary to configure it to listen locally if the
  builtin desktop needs to be used.