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 VirtualBox to your NixOs system configuration at ``/etc/nixos/configuration.nix``::

    virtualisation.virtualbox.host.enable = true;
    # Use VirtualBox installation without GUI and Qt dependency:
    virtualisation.virtualbox.host.headless = true;

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_DEFAULT_PROVIDER=virtualbox vagrant up

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

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

5. 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 payments 192.168.67.21
      HostName 127.0.0.1
      User vagrant
      [...]

  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.

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

    $EDITOR secrets/users.nix

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