README.rst

Set up and use a network of local development VMs
-------------------------------------------------

... using `Vagrant <https://www.vagrantup.com/>`_ to manage VirtualBox VMs.
(The author of this documentation wasted a lot of time trying to get Vagrant to work with KVM/libvirt.
Issues with networking that looked like guest misconfigurations vanished after changing to the better-tested combination of Vagrant and VirtualBox.)

This requires `NixOS <https://nixos.org/>`_.
Nix without the OS will not work.


Use the local development environment
`````````````````````````````````````

0. Add to your NixOS system configuration at ``/etc/nixos/configuration.nix`` (and rebuild)::

    # Enable libvirt - likely incompatible with virtualisation.virtualbox!
    virtualisation.libvirtd.enable = true;
    # Required for LibVirt
    security.polkit.enable = true;
    # Enable HW acceleration if (nested virtualisation is) available
    #boot.kernelModules = [ "kvm-amd" "kvm-intel" ];

1. Enter the morph local grid directory::

    cd morph/grid/local

2. Enter the project's nix-shell::

    nix-shell ../../../shell.nix

3. Build and start the VMs::

    vagrant up --provider=libvirt

   Optionally, to switch from QEMU to KVM virtualization, edit the virtual machine definition of all the machines and replace the "qemu" on the first line with "kvm"::

    sudo virsh list
    sudo virsh edit <machine id> (once for every machine)
    vagrant halt
    vagrant up


4. Then, add the Vagrant SSH configuration to your user's ``~/.ssh/config`` file::

    install -d ~/.ssh ; vagrant ssh-config >> ~/.ssh/config

   Latest Morph honors the ``SSH_CONFIG_FILE`` environment variable (`since 3f90aa88 (March 2020, v 1.5.0) <https://github.com/DBCDK/morph/commit/3f90aa885fac1c29fce9242452fa7c0c505744ef#diff-d155ad793bd62e6ea4c44ba985049ecb13a4f4f32f799791b2bce695a16c0101>`_), so in the future this should get a bit more convenient.

5. Create a ``public-keys/users.nix`` file with your SSH key (see ``public-keys/users.nix.example`` for the format) so you'll be able to log in after deploying the new configuration::

    $EDITOR public-keys/users.nix

6. Then, build and deploy our software to the Vagrant VMs::

    morph build grid.nix
    morph push grid.nix
    morph deploy grid.nix boot
    vagrant halt
    vagrant up
    morph upload-secrets grid.nix

You should now be able to log in with the users and keys you set in your ``users.nix`` file.