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.)


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

0. Enter the morph local grid directory::

    cd morph/grid/local

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

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

2. Build and start the VMs::

    VAGRANT_DEFAULT_PROVIDER=virtualbox vagrant up

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

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

4. Edit the generated configuration: Add the ``publicIP`` addresses from ``grid.nix`` to ssh config **Host** match blocks (**not** HostName) so the ``Host`` lines all read like::

    Host payments1 192.168.67.21
      HostName 127.0.0.1
      User vagrant
      [...]

From version 1.5.0 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 will get a bit more convenient.

5. Add your SSH key to ``users.nix`` so you'll be able to log in after deploying the new configuration::

    $EDITOR secrets/users.nix

5. 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.