diff --git a/docs/source/dev/README.rst b/docs/source/dev/README.rst index e1a793f3ac70a320ed52c20e0b2128696455a7c9..904e8b3be07bdcc1473a3c1fe22afe8ffb0e15a2 100644 --- a/docs/source/dev/README.rst +++ b/docs/source/dev/README.rst @@ -45,5 +45,11 @@ Architecture overview .. graphviz:: architecture-overview.dot +.. include:: + ../../../morph/grid/local/README.rst + + + + .. _Nix: https://nixos.org/nix diff --git a/morph/grid/local/README.rst b/morph/grid/local/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..ddccc67def0596516284b7a71189b2a50105ee38 --- /dev/null +++ b/morph/grid/local/README.rst @@ -0,0 +1,48 @@ +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 +````````````````````````````````````` + +Build and start the VMs:: + + VAGRANT_DEFAULT_PROVIDER=virtualbox vagrant up + +Then:: + + morph build grid.nix + morph push grid.nix + morph deploy grid.nix switch + diff --git a/morph/grid/local/Vagrantfile b/morph/grid/local/Vagrantfile new file mode 100644 index 0000000000000000000000000000000000000000..7c20fddda1516d31abd65c9850abaf7619ce8030 --- /dev/null +++ b/morph/grid/local/Vagrantfile @@ -0,0 +1,44 @@ +# -*- mode: ruby -*- +# vi: set ft=ruby : + +# This Vagrantfile worked for Florian Sesser using Vagrant 2.2.16dev and +# the VirtualBox Hypervisor. Earlier Vagrant and LibVirt did not work. + +Vagrant.configure("2") do |config| + # For a complete reference, please see the online documentation at + # https://docs.vagrantup.com. + + config.vm.define "payments1" do |config| + config.vm.hostname = "payments1" + config.vm.box = "esselius/nixos" + config.vm.box_version = "20.09" + config.vm.box_check_update = false + config.vm.network "private_network", ip: "192.168.67.21" + end + + config.vm.define "storage1" do |config| + config.vm.hostname = "storage1" + config.vm.box = "esselius/nixos" + config.vm.box_version = "20.09" + config.vm.box_check_update = false + config.vm.network "private_network", ip: "192.168.67.22" + end + + config.vm.define "storage2" do |config| + config.vm.hostname = "storage2" + config.vm.box = "esselius/nixos" + config.vm.box_version = "20.09" + config.vm.box_check_update = false + config.vm.network "private_network", ip: "192.168.67.23" + end + + # To make the VMs assign the static IPs to the network interfaces we need a rebuild: + config.vm.provision "shell", inline: "nixos-rebuild switch" + + config.trigger.after :up do |trigger| + trigger.info = "Hostname and IP address this host actually uses:" + trigger.run_remote = {inline: "echo `hostname` `ifconfig | egrep -o '192.168.67.[0-9]* '`"} + end + +end +