README.rst

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

... using `Vagrant <https://www.vagrantup.com/>`_ to manage VirtualBox VMs [#]_.
To get started, first install Vagrant and make sure it works.
One possible way to do it in NixOS:

1. Install Vagrant, by adding the packages:

  - ``vagrant`` (orchestrating virtual machines on the command line)
     - Only use when version >= 2.2.16 has become available.  Else see below.
  - Optional: ``packer`` (for creating your own VM images)

2. Add configuration to install and enable VirtualBox:

  - ``virtualisation.virtualbox.host.enable = true;``

3. Add your user to the ``vboxusers`` group, for example:

  - ``users.extraGroups.vboxusers.members = [ "flo" "jp" ];``


.. [#] 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.


Pre-Vagrant 2.2.16: Get Vagrant with the required fixes for NixOS guests
````````````````````````````````````````````````````````````````````````

The Vagrant nixos-guest template `received a critical update on 2021-03-08 <https://github.com/hashicorp/vagrant/commit/990d94ed9d0b3092e855bc1bb9deeeb7aa7792cf>`_ which came out with Vagrant version 2.2.16.

If you run an older Nixpkgs, retrieve and use the latest Vagrant development version like so::

  NIX_PATH=nixpkgs=https://github.com/NixOS/nixpkgs/archive/refs/heads/master.tar.gz nix-shell -p vagrant


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

1. Build and start the VMs::

    VAGRANT_DEFAULT_PROVIDER=virtualbox vagrant up

2. Then, once::

    vagrant ssh-config > ./vagrant-ssh-config

3. Edit the output: Add the IPs from ``grid.nix`` to the ``vagrant-ssh-config`` **Host match blocks** so the config reads like::

    Host payments1 192.168.67.21
      HostName 192.168.67.21
      User vagrant
      Port 22
      [...]

4.  Then, make morph use this ssh config either - with newer morph [#]_ - by pointing it to it::

     export SSH_CONFIG_FILE=./vagrant-ssh-config

  Or, with older morph, adding the config to your user's ``~/.ssh/config`` file.

  .. [#]  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>`_.

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

    morph build grid.nix
    morph push grid.nix
    morph upload-secrets grid.nix
    morph deploy grid.nix switch

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