📚 [Documentation]: Doc related to VM

[huard]

Description

Documentation found in pavics-sdi on VM installation that is probably best suited for here.

================
VM configuration
================

For development and testing it can be useful to install pavics-sdi in a virtual machine. Here we describe the configuration for an `OpenStack`_ environment.

Data volumes
============

* Attach 2 openstack volumes to the vm (take note of its name looking like ``/dev/vdx``)
* Mount them at ``/data`` and ``/geoserver_data`` using the following command::

     mount /dev/vdx /[geoserver_]data

* New volumes must first be formatted using the command :command:`mkfs.ext4 /dev/vdx`

Docker volume
=============

Docker can take a lot of space to maintain all containers and the default directory ``/var/lib/docker`` on the host can rapidly run out of disk space. The easy solution is to mount a bigger volume at this position:

#. Attach an openstack volume to the vm (take note of its name looking like ``/dev/vdx``)
#. Stop the docker service : :command:`service docker stop`
#. Mount the new volume at :file:`/var/lib/docker` using the following command::

      mount /dev/vdx /var/lib/docker

#. Start the docker service: :command:`service docker start`

Automount
=========

To automatically mount volumes at reboot we modified the :file:`/etc/fstab` file to include the attached `OpenStack`_ volumes. For example (mind the tabspaces):

.. code-block:: bash
   :caption: :file:`/etc/fstab`

   LABEL=cloudimg-rootfs   /        ext4   defaults        0 0
   /dev/vdb        none            swap    sw,comment=cloudconfig  0       0
   /dev/vdd        /data           ext4    defaults        0 0
   /dev/vdc        /var/lib/docker ext4    defaults        0 0


Hostname resolution
===================

The virtual machine is publicly visible by using the `OpenStack`_ external IP. But this IP is not visible from inside, the internal IP must be used. To resolve this issue, create a DNS entry mapping a hostname to the external IP and edit :file:`/etc/hosts` from inside the VM so that the same hostname maps the internal IP.

For example, ``outarde.crim.ca`` is resolved as 132.217.140.52 (OpenStack external IP) everywhere but from the inside of this vm the :file:`/etc/hosts` config resolve this hostname to 192.168.101.91 (OpenStack internal IP).


.. _`OpenStack`: https://www.openstack.org/

References

Information	Value
Server/Platform URL
Related issues/PR
Related documentation

[tlvu]

Vagrant Virtualbox VM can be spawned automatically with instruction here

birdhouse-deploy/birdhouse/README.rst

Lines 191 to 250 in 93ed91b

	Vagrant instructions
	--------------------
	Vagrant allows us to quickly spin up a VM to easily reproduce the runtime
	environment for testing or to have multiple flavors of PAVICS with slightly
	different combinations of the parts all running simultaneously in their
	respective VM, allowing us to see the differences in behavior.
	See `vagrant_variables.yml.example </vagrant_variables.yml.example>`_ (:download:`download </vagrant_variables.yml.example>`) for what's
	configurable with Vagrant.
	If using Centos box, follow `disk-resize <vagrant-utils/disk-resize>`_ (:download:`download </birdhouse/vagrant-utils/disk-resize>`) after
	first ``vagrant up`` failure due to disk full. Then ``vagrant reload && vagrant
	provision`` to continue. If using Ubuntu box, no manual steps required,
	everything just works.
	Install `VirtualBox <https://www.virtualbox.org/wiki/Downloads>`_, both the
	platform and the extension pack, and `Vagrant <https://www.vagrantup.com/downloads.html>`_.
	One time setup:
	.. code-block::
	# Clone this repo and checkout the desired branch.
	# Follow instructions and fill up infos in vagrant_variables.yml
	cd .. # to the folder having the Vagrantfile
	cp vagrant_variables.yml.example vagrant_variables.yml
	Starting and managing the lifecycle of the VM:
	.. code-block::
	# start everything, this is the only command needed to bring up the entire
	# PAVICS platform
	vagrant up
	# get bridged IP address
	vagrant ssh -c "ip addr show enp0s8|grep 'inet '"
	# get inside the VM
	# useful to manage the PAVICS platform as if Vagrant is not there
	# and use pavics-compose.sh as before
	# ex: cd /vagrant/birdhouse; ./pavics-compose.sh ps
	vagrant ssh
	# power-off VM
	vagrant halt
	# delete VM
	vagrant destroy
	# reload Vagrant config if vagrant_variables.yml or Vagrantfile changes
	vagrant reload
	# provision again (because all subsequent vagrant up won't provision again)
	# useful to test all provisioning scripts or to bring a VM at unknown state,
	# maybe because it was provisioned too long ago, to the latest state.
	# not needed normally during tight development loop
	vagrant provision

Could this be closed?