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;
    # Save bytes and build time, optional but recommended:
    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

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

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.