Skip to content

Commit

Permalink
Update virtualization doc with new template and formatting (#724)
Browse files Browse the repository at this point in the history 
* Update virtualization doc with new template and formatting
* Update virtualization_quickstart.rst
* Add previous author
* Add 80 characters to section headings
  • Loading branch information
@Chrisganta
Chrisganta committed Oct 18, 2021
1 parent 861daf9 commit 4ae56cb
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 50 deletions.
Binary file added doc/images/projects/osgeolive/vmdk_user_interface.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
130 changes: 80 additions & 50 deletions doc/quickstart/virtualization_quickstart.rst
View file
@@ -1,5 +1,5 @@
:Author: OSGeoLive
:Author: Micha Silver
:Author: Christopher Ganta, Gayathri Krishnaswamy, Nelson Guya, Micha Silver
:Reviewer: Cameron Shorter, Jirotech
:Reviewer: Stephen Woodbridge
:Version: osgeolive11.0
Expand All @@ -9,121 +9,151 @@
Running in a Virtual Machine
********************************************************************************

This Quick Start describes one way to run OSGeoLive within a VirtualBox virtual machine. For other methods, follow links from the "See Also" section below.

Virtual Machine Advantages
Overview
--------------------------------------------------------------------------------

* The response speed of a VM is much faster than on the DVD, and typically comparable with installing directly on the host machine.

* All configuration changes, software updates, and saved files are permanent, just like on any "regular" computer. So:
This Quick Start describes one way to run OSGeoLive within a VirtualBox virtual machine (VM). For other methods, follow links from the "See Also" section below.

* You can customize and update the system
* You can save your work within the VM
* You can install additional software
.. note::
To learn more about the benefits of virtualization, see `Virtualization <https://en.wikipedia.org/wiki/Virtualization>`_ in Wiki

* You can backup your virtual machine installation.

System Requirements
Prerequisites
--------------------------------------------------------------------------------

* RAM: 2 GB at least. The Lubuntu system runs well with 1 GB of RAM, and you'll need to keep at least the same amount of memory for your host system.
So a total of 2 GB will be needed for smooth operation. Some applications, like GeoServer, needs the virtual machine to have at least 2GB of RAM. So if possible, consider providing 2 GB or more for your virtual machine.
* Spare Hard Disk Space: The virtual disk file (vmdk) from :doc:`live.osgeo.org <../download>` unzips to almost 10 GB. You'll also want more space to allow some room to work on the virtual machine. So 20 GB is a good recommendation.
* CPU: Any CPU will do, but a processor which supports "Virtualization Technology" will be faster. You can check your computer CPU `here <https://www.intel.com/content/www/us/en/support/articles/000005486/processors.html>`__.
**Software**

Most machines produced in the last 4-5 years will meet these requirements.
* Download `Virtual Box <https://www.virtualbox.org/>`_ for your platform, and install the software. On Windows run the installer, or on Ubuntu-like Linux systems run the following:

``apt-get install virtualbox-ose``

Howto
--------------------------------------------------------------------------------
* Download the OSGeo Virtual disk file (vmdk) from :doc:`live.osgeo.org <../download>`.

**Downloads**
* Under **osgeolive-vm**, download the 7-zip file. Then unzip the downloaded file (using `7zip <https://www.7-zip.org>`_ ).

Download `Virtual Box <https://www.virtualbox.org/>`_ for your platform, and install the software. On Windows run the installer, or on Ubuntu-like Linux systems do the following:
**Hardware**

``apt-get install virtualbox-ose``
* **RAM**: Minimum 2 GB. The Lubuntu system runs well with 1 GB of RAM, and you'll need to keep at least the same amount of memory for some of your applications (such as GeoServer). So a total of 2 GB is recommended for a smooth operation.
* **Spare**: Minimum 20 GB Hard Disk Space. The virtual disk file (vmdk) from :doc:`live.osgeo.org <../download>` unzips to almost 10 GB. You'll also want more space to allow some room to work on the virtual machine. So a total of 20 GB is a good recommendation.
* **CPU**: Any CPU will do, but a processor which supports "Virtualization Technology" will be faster. Check if your computer supports `Virtualization Technology <https://www.intel.com/content/www/us/en/support/articles/000005486/processors.html>`_

.. note::
Most machines produced after 2010 will meet these requirements.

In addition download the OSGeo Virtual disk file (vmdk) from :doc:`live.osgeo.org <../download>`.
Click on the "Download virtual machine" button. Then unzip the downloaded file (using `7zip <https://www.7-zip.org>`_ ).

Step 1 : Create a Virtual Machine
--------------------------------------------------------------------------------

**Create a Virtual Machine**
1. Start the VirtualBox application and click **New**. Create Virtual Machine pop up is displayed.

Start the VirtualBox application and click on the New button to create a new VM, and then Next.

.. image:: /images/projects/osgeolive/virtualbox.png
:scale: 50 %

Enter a name such as OSGeoLive, and choose Linux as the "Operating system", and Ubuntu as the "Version".
2. Enter a name such as OSGeoLive, and select Linux as the "Operating system", and Ubuntu as the "Version", and then click **Next**.

.. image:: /images/projects/osgeolive/virtualbox_select_name.png
:scale: 70 %

In the next screen set the memory to 1024 MB (or more if your host computer has more than 4GB, like in the screenshot below).
3. In the next screen set the memory to at least 1024 MB (or more if your host computer has more than 4GB, like in the screenshot below).

.. image:: /images/projects/osgeolive/vmdk_memory.png
:scale: 65 %

Continue to the next screen and choose "Use an existing virtual hard disk file". Now click on the button (a folder icon) to browse to where you saved the OSGeoLive vmdk-file. Select this file, press Next and Create.
4. Continue to the next screen and select **Use an existing virtual hard disk file**. Click the folder icon to browse to where you saved the OSGeoLive vmdk-file. Select the file, click **Next** and **Create**.

You should now be able to view the **OSGeoLive** listed in your virtual box.

.. image:: /images/projects/osgeolive/vmdk_disk.png
:scale: 65 %

**Config tips and tweaks**

Once the VM is created, click on the Settings button. In the "General" section, go to the Advanced tab, and click to select "Show at top of screen" for the Mini toolbar.
Step 2: Configure VM
--------------------------------------------------------------------------------

**VM Settings**

.. image:: /images/projects/osgeolive/vmdk_general_advanced.png

1. Once the VM is created, click the **Settings** button. In the **User Interface** section, click to select **Show at top of screen** for the Mini toolbar.

.. image:: /images/projects/osgeolive/vmdk_user_interface.png
:scale: 65 %

Go to the "Display" section and increase video memory to 32 or 64 MB. In some host operating systems, it may be required to "Enable 3D Acceleration" for display to work properly.
2. Go to the **Display** section and increase video memory to 32 or 64 MB. In some host operating systems, it may be required to "Enable 3D Acceleration" for display to work properly.

.. image:: /images/projects/osgeolive/vmdk_display.png
:scale: 65 %

In addition, move to the "Shared Folders" section, and click the "Add folder" (green + icon on the right) to find a directory on your host computer that you wish to share inside the VM.
**Add shared folders to access files from host**

3. Go to the **Shared Folders** section, and click the **Add folder** (green + icon on the right) to find a directory on your host computer that you wish to share inside the VM.

.. image:: /images/projects/osgeolive/vmdk_shared_folders.png
:scale: 65 %

You can choose to make the shared folder read-only, and auto-mounted. Once the "Folder path" and "Folder name" are defined, click OK, and again OK to finish and close the settings window.


**Running the Virtual Machine**
Step 3 : Running the Virtual Machine
--------------------------------------------------------------------------------

Now bootup the VM by clicking the Start (green arrow) button.
Now bootup the VM by clicking the **Start** (green arrow) button.

You should install the virtualbox guest additions, this will allow you to use full-screen mode.
* The OSGeo-Live virtual display (i.e., the window size) may be very small, and will not be able to increase until you install Guest Additions. You should install the virtualbox guest additions, this will allow you to use full-screen mode.

``sudo apt-get install --yes virtualbox-guest-dkms virtualbox-guest-utils virtualbox-guest-x11``

When you install the iso on the VM, the username must be set to "user"
(Alternative) If the above command does not work, use the following alternative:

1. From the VirtualBox Devices menu, select **Insert Guest Additions CD Image**
2. Click **OK** when prompted to open the removable media in **File Manager**.
3. In **File Manager**, select **Tools** → **Open Current Folder** in terminal.
4. In the terminal type:

``sudo ./VBoxLinuxAdditions.run``

The user "user" is not a member of the "users" group on the OSGeoLive virtual machine. This prevents some tools from writing to its data directory and causes some software to fail to start.
5. Press ENTER.

The solution is to fix the vmdk with the following one-time procedure:

Step 4 : Set OSGeoLive user
--------------------------------------------------------------------------------

.. note::
Some tools configured on OSGeoLive rely of "user" to be in the "users" group so they can write into the data directory. If not set, these tools will fail when run.

1. Start a terminal.
2. Run "sudo adduser user users".
2. Run ``sudo adduser user users``.
3. Apply this change by starting a new desktop session: either restart the virtual machine or log out and log back in (username "user", password "user").

Also once the OSGeo system starts, add yourself to the vboxsf group so that the shared folders (defined above) are accessible by running in a terminal window:
Step 5: Access shared folders
--------------------------------------------------------------------------------

* Add yourself to the vboxsf group so that the shared folders (defined above) are accessible by running in a terminal window:

``user@osgeolive:~$ sudo usermod -a -G vboxsf user``
``user@osgeolive:~$ sudo usermod -a -G vboxsf user``

In the above example, we defined a Shared Folder path on the host system and named it "GIS" in the VM Settings. The shared folder will appear in the file system under /media/sf_GIS/. To mount this folder in the user's home directory, for example, in a terminal run:

``user@osgeolive:~$ mkdir GIS``
Step 6: Mount shared folder
--------------------------------------------------------------------------------

* In the above example, we defined a Shared Folder path on the host system and named it "GIS" in the VM Settings. The shared folder will appear in the file system under /media/sf_GIS/. To mount this folder in the user's home directory, for example, in a terminal run:

``user@osgeolive:~$ mkdir GIS``

``user@osgeolive:~$ sudo mount -t vboxsf -o uid=user,rw GIS /home/user/GIS``

``user@osgeolive:~$ sudo mount -t vboxsf -o uid=user,rw GIS /home/user/GIS``
Now files on your host machine in the chosen folder will also be available in the VM in the "GIS" folder in the user's home directory.

Congratulations, you should now have OSGeoLive running in a Virtual Machine.

Next steps:
--------------------------------------------------------------------------------

Now files on your host machine in the chosen folder will also be available in the VM in the "GIS" folder in user's home directory.
Why don't you try running some applications, as described in the `OSGeoLive Quickstart <https://live.osgeo.org/en/quickstart/osgeolive_quickstart.html>`_

See Also:
--------------------------------------------------------------------------------
* OSGeo wiki pages:
`Other ways to create a Virtual Machine <https://wiki.osgeo.org/wiki/Live_GIS_Virtual_Machine>`_

* OSGeo wiki pages: `Other ways to create a Virtual Machine <https://wiki.osgeo.org/wiki/Live_GIS_Virtual_Machine>`_
* :doc:`osgeolive_quickstart`
* :doc:`osgeolive_install_quickstart`
* :doc:`usb_quickstart`

0 comments on commit 4ae56cb

Please sign in to comment.