### Declaring a MicroVM

The hosts nixosSystems modules should be declared using the ```makeMicroVM``` helper function.
Use durruti as orientation:
``` nix
    modules = makeMicroVM "durruti" "10.0.0.5" [
      ./durruti/configuration.nix
    ];
```

"durruti" is the hostname.  
"10.0.0.5" is the IP assigned to its tap interface.  

### Testing MicroVMs locally
MicroVMs can be built and run easily on your localhost for development.  
We provide the script ```run-vm``` to handle stuff like development (dummy) secrets, sharing directories, ect. easily.
Usage examples:
``` bash
# run without args to get available options and usage info
run-vm

# run nextcloud locally with dummy secrets
run-vm nextcloud --dummy-secrets

# share a local folder as /var/lib dir so that nextcloud application data stays persistent between boots
mkdir /tmp/nextcloud
run-vm nextcloud --dummy-secrets --varlib /tmp/nextcloud

# enable networking to provide connectivity between multiple vms
# for that the malobeo hostBridge must be enabled on your host
# this example deploys persistent grafana on overwatch and fetches metrics from infradocs
mkdir overwatch
run-vm overwatch --networking --varlib /tmp/overwatch
run-vm infradocs --networking
```



### Fully deploy microvms on local host
In order to test persistent microvms locally we need to create them using the ```microvm``` command.  
This is necessary to be able to mount persistent /etc and /var volumes on those hosts.  
Do the following:

Prepare your host by including `microvm.nixosModules.host` in your `flake.nix` [Microvm Docs](https://astro.github.io/microvm.nix/host.html)


```bash
# go into our repo and start the default dev shell (or use direnv)
nix develop .#

# create a microvm on your host (on the example of durruti)
sudo microvm -c durruti -f git+file:///home/username/path/to/infrastructure/repo

# start the vm
sudo systemctl start microvm@durruti.service

# this may fail, if so we most probably need to create /var /etc manually, then restart
sudo mkdir -p /var/lib/microvms/durruti/{var,etc}

# now you can for example get the rsa host key from /var/lib/microvms/durruti/etc/ssh/

# alternatively u can run the vm in interactive mode (maybe stop the microvm@durruti.service first)
microvm -r durruti

# after u made changes to the microvm update and restart the vm 
microvm -uR durruti

# deleting the vm again:
sudo systemctl stop microvm@durruti.service
sudo systemctl stop microvm-virtiofsd@durruti.service
sudo rm -rf /var/lib/microvms/durruti
```


### Host Setup

#### Network Bridge
To provide network access to the VMs a bridge interface needs to be created on your host.
For that:
- Add the infrastructure flake as input to your hosts flake  
- Add ```inputs.malobeo.nixosModules.malobeo``` to your hosts imports
- enable the host bridge: ```services.malobeo.microvm.enableHostBridge = true;```

If you want to provide Internet access to the VM it is necessary to create a nat.
This could be done like this:
``` nix
networking.nat = {
  enable = true;
  internalInterfaces = [ "microvm" ];
  externalInterface = "eth0"; #change to your interface name
};
```
#### Auto Deploy VMs
By default no MicroVMs will be initialized on the host - this should be done using the microvm commandline tool.
But since we want to always deploy certain VMs it can be configured using the ```malobeo.microvm.deployHosts``` option.
VMs configured using this option will be initialized and autostarted at boot.
Updating still needs to be done imperative, or by enabling autoupdates.nix

The following example would init and autostart durruti and gitea:
``` nix
malobeo.microvm.deployHosts = [ "durruti" "gitea" ];
```