Replace Outdated Windows Install Instructions with VM Instructions

ReactionMechanismGenerator · Jan 14, 2019 · 690a0dc · 690a0dc
1 parent f0ca8bc
commit 690a0dc
Show file tree

Hide file tree

Showing 36 changed files with 209 additions and 11 deletions.
diff --git a/documentation/source/users/rmg/installation/anacondaDeveloper.rst b/documentation/source/users/rmg/installation/anacondaDeveloper.rst
@@ -4,7 +4,7 @@
 Installation by Source Using Anaconda Environment for Unix-based Systems: Linux and Mac OSX
 *******************************************************************************************
 
-* Download and install the `Anaconda Python Platform <http://continuum.io/downloads>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). When prompted to append Anaconda to your PATH, select or type Yes.  Install the Anaconda folder inside your home directory (typically ``/home/YourUsername/`` in Linux and ``/Users/YourUsername`` in Mac).
+* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). When prompted to append Anaconda to your PATH, select or type Yes.  Install the Anaconda folder inside your home directory (typically ``/home/YourUsername/`` in Linux and ``/Users/YourUsername`` in Mac).
 
 * Install `Git <https://git-scm.com/>`_, the open source version control package through the Terminal. **For Mac OS X**: Git is already packages with OS X 10.9 or later, but requires installation of Xcode's Command Line Tools. Skip the git installation and run it through the terminal, where you will be prompted to install the Command Line Tools if they are not already installed. ::
 

diff --git a/documentation/source/users/rmg/installation/anacondaDeveloperWindows.rst b/documentation/source/users/rmg/installation/anacondaDeveloperWindows.rst
@@ -5,7 +5,7 @@ Installation by Source Using Anaconda Environment for Windows
 *************************************************************
 
 
-* Download and install the `Anaconda Python Platform <http://continuum.io/downloads>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). We recommend changing the default install path to ``C:\Anaconda\`` in order to avoid spaces in the install path and be easily accessible. It is recommended to append Anaconda to your PATH as well as setting it as your default Python executable.  All other settings can remain as their defaults.
+* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). We recommend changing the default install path to ``C:\Anaconda\`` in order to avoid spaces in the install path and be easily accessible. It is recommended to append Anaconda to your PATH as well as setting it as your default Python executable.  All other settings can remain as their defaults.
 
 .. image:: images/AnacondaInstallWindows.png
     :align: center

diff --git a/documentation/source/users/rmg/installation/anacondaUser.rst b/documentation/source/users/rmg/installation/anacondaUser.rst
@@ -5,7 +5,7 @@ Binary Installation Using Anaconda for Unix-Based Systems: Linux and Mac OSX
 ****************************************************************************
 
 
-* Download and install the `Anaconda Python Platform <http://continuum.io/downloads>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). When prompted to append Anaconda to your PATH, select or type Yes.
+* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). When prompted to append Anaconda to your PATH, select or type Yes.
 
 * Install both RMG and the RMG-database binaries through the Terminal.   Dependencies will be installed automatically. It is safest to make a new Anaconda environment for RMG and its dependencies. Type the following command into the Terminal to create the new environment named 'rmg_env' containing the latest stable version of the RMG program and its database. ::
 

diff --git a/documentation/source/users/rmg/installation/anacondaUserWindows.rst b/documentation/source/users/rmg/installation/anacondaUserWindows.rst
@@ -4,7 +4,7 @@
 Binary Installation Using Anaconda for Windows
 **********************************************
 
-* Download and install the `Anaconda Python Platform <http://continuum.io/downloads>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). We recommend changing the default install path to ``C:\Anaconda\`` in order to avoid spaces in the install path and be easily accessible. It is recommended to append Anaconda to your PATH as well as setting it as your default Python executable.  All other settings can remain as their defaults.
+* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). We recommend changing the default install path to ``C:\Anaconda\`` in order to avoid spaces in the install path and be easily accessible. It is recommended to append Anaconda to your PATH as well as setting it as your default Python executable.  All other settings can remain as their defaults.
 
 .. image:: images/AnacondaInstallWindows.png
     :align: center

diff --git a/documentation/source/users/rmg/installation/images/Ubuntu1804.png b/documentation/source/users/rmg/installation/images/Ubuntu1804.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_1.png b/documentation/source/users/rmg/installation/images/VBoxInstall_1.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_2.png b/documentation/source/users/rmg/installation/images/VBoxInstall_2.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_3.png b/documentation/source/users/rmg/installation/images/VBoxInstall_3.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_4.png b/documentation/source/users/rmg/installation/images/VBoxInstall_4.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_5.png b/documentation/source/users/rmg/installation/images/VBoxInstall_5.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_6.png b/documentation/source/users/rmg/installation/images/VBoxInstall_6.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxInstall_7.png b/documentation/source/users/rmg/installation/images/VBoxInstall_7.png
diff --git a/documentation/source/users/rmg/installation/images/VBoxNew.png b/documentation/source/users/rmg/installation/images/VBoxNew.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_Erase_Disk_Okay.png b/documentation/source/users/rmg/installation/images/VBox_Erase_Disk_Okay.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_IDE.png b/documentation/source/users/rmg/installation/images/VBox_IDE.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_IDE_complete.png b/documentation/source/users/rmg/installation/images/VBox_IDE_complete.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_Install_Ubuntu.png b/documentation/source/users/rmg/installation/images/VBox_Install_Ubuntu.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_Normal_Install.png b/documentation/source/users/rmg/installation/images/VBox_Normal_Install.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_Settings.png b/documentation/source/users/rmg/installation/images/VBox_Settings.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_Start.png b/documentation/source/users/rmg/installation/images/VBox_Start.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_VDI.png b/documentation/source/users/rmg/installation/images/VBox_VDI.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_VM_name.png b/documentation/source/users/rmg/installation/images/VBox_VM_name.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_browse_for_disk.png b/documentation/source/users/rmg/installation/images/VBox_browse_for_disk.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_choose_iso_1.png b/documentation/source/users/rmg/installation/images/VBox_choose_iso_1.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_choose_iso_2.png b/documentation/source/users/rmg/installation/images/VBox_choose_iso_2.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_cpus.png b/documentation/source/users/rmg/installation/images/VBox_cpus.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_create_hard_disk.png b/documentation/source/users/rmg/installation/images/VBox_create_hard_disk.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_disk_size.png b/documentation/source/users/rmg/installation/images/VBox_disk_size.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_dynamic_storage.png b/documentation/source/users/rmg/installation/images/VBox_dynamic_storage.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_memory.png b/documentation/source/users/rmg/installation/images/VBox_memory.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_optical_disk.png b/documentation/source/users/rmg/installation/images/VBox_optical_disk.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_partitions.png b/documentation/source/users/rmg/installation/images/VBox_partitions.png
diff --git a/documentation/source/users/rmg/installation/images/VBox_video_mem.png b/documentation/source/users/rmg/installation/images/VBox_video_mem.png
diff --git a/documentation/source/users/rmg/installation/images/VirtualBoxDownload.png b/documentation/source/users/rmg/installation/images/VirtualBoxDownload.png
diff --git a/documentation/source/users/rmg/installation/index.rst b/documentation/source/users/rmg/installation/index.rst
@@ -16,6 +16,19 @@ developers will get back to you as soon as we can.  You can also search for your
 page to see if there are already solutions in development.  Alternatively, you can email us at
 rmg_dev@mit.edu
 
+Installation on a Windows Platform
+====================================
+
+Due to difficulties with dependencies, installation on Windows directly is no longer supported. Instead, it is
+recommended to run a Linux virtual machine from Windows and follow either the instructions for basic users
+(binary installation using Anaconda) or the instructions for developers.
+
+.. toctree::
+    :maxdepth: 1
+
+    virtualMachineSetup
+
+
 For Basic Users: Binary Installation Using Anaconda
 ===================================================
 
@@ -28,8 +41,6 @@ RMG's thermodynamic and kinetics databases.
     :maxdepth: 1
 
     anacondaUser
-    anacondaUserWindows
-    windowsEnvironment
 
 
 For Developers: Installation by Source Using Anaconda Environment
@@ -44,20 +55,23 @@ source code updates and patches through Github.
     :maxdepth: 1
 
     anacondaDeveloper
-    anacondaDeveloperWindows
-    windowsEnvironment
     updatingSourceCode
 
-For Developers: Direct Installation by Source without Anaconda
-==============================================================
+Archive of Unsupported Installation Methods
+===========================================
 
-The installation approach in this section is not recommended and also not maintained by RMG developer team. This is only a record for people who cannot use Anaconda.
+Below are old installation techniques that are no longer supported, including instructions for installation without
+using Anaconda and the old installation instructions for Windows. These instructions are no longer maintained, and are
+not recommended for use.
 
 .. toctree::
     :maxdepth: 1
 
     linux
     macos
+    anacondaUserWindows
+    anacondaDeveloperWindows
+    windowsEnvironment
 
 Dependencies
 ============

diff --git a/documentation/source/users/rmg/installation/virtualMachineSetup.rst b/documentation/source/users/rmg/installation/virtualMachineSetup.rst
@@ -0,0 +1,184 @@
+.. _virtualMachineSetup:
+
+************************************************
+Setting up a Linux Virtual Machine from Windows
+************************************************
+
+Downloading a Linux .iso File
+================================
+
+If this is your first time using a Linux operating system, we recommend using Ubuntu 18.04, as it is one of the most
+popular Linux distributions out there, with plenty of support available online. Otherwise you are welcome to try out
+any other Linux distribution you like (see `Linux DistroWatch`_).
+
+.. _Linux DistroWatch: https://distrowatch.com/
+.. _Ubuntu: https://www.ubuntu.com/#download
+
+1. Go to the Ubuntu_ website and click on the download link for 18.04 LTS (Desktop, not Server). Note that newer
+versions of Ubuntu might be available, but we recommend downloading only the LTS (long term support) versions. Note that
+Ubuntu is completely free to download and use, so you do not need to make a donation if prompted.
+
+.. image:: images/Ubuntu1804.png
+    :align: center
+
+2. The .iso file is typically around 2 GB in size, so the file will take a while to download. While this is happening,
+feel free to proceed with the remaining sections.
+
+
+Choosing a VM Software
+=========================
+
+There a quite a few software options for running a virtual machine from Windows, including `VMware Workstation Pro`_
+and `Oracle VirtualBox`_. VMware Workstation Pro is the recommended choice, though check to see if your institution has
+access to it (since it is not free). If not, VirtualBox (which is free) runs well and will work just as fine. Use the
+hyperlinks below to jump ahead to the setup instructions for the virtual machine software of your choice.
+
+.. _VMware Workstation Pro: https://my.vmware.com/en/web/vmware/info/slug/desktop_end_user_computing/vmware_workstation_pro/15_0
+.. _Oracle VirtualBox: https://www.virtualbox.org/wiki/Downloads
+
+
+:ref:`WorkstationPro`
+
+:ref:`VirtualBox`
+
+.. _WorkstationPro:
+
+Setting up a Linux Virtual Machine using Workstation Pro
+==========================================================
+
+
+.. _VirtualBox:
+
+Setting up a Linux Virtual Machine using VirtualBox
+==========================================================
+1. Go to the `Oracle VirtualBox`_ website and click on the download link for "Windows hosts" (highlighted orange in the
+image below)
+
+.. image:: images/VirtualBoxDownload.png
+    :align: center
+
+2. Once the download is complete, launch the executable. Select the "Next" button a few times to install VirtualBox
+with the default settings. If prompted download any necessary drivers. After installation, launch VirtualBox.
+
+.. image:: images/VBoxInstall_1.png
+    :align: center
+
+.. image:: images/VBoxInstall_2.png
+    :align: center
+
+.. image:: images/VBoxInstall_3.png
+    :align: center
+
+.. image:: images/VBoxInstall_4.png
+    :align: center
+
+.. image:: images/VBoxInstall_5.png
+    :align: center
+
+.. image:: images/VBoxInstall_6.png
+    :align: center
+
+3. From the VirtualBox Manager window, click on the blue star labeled "New" to begin creating your Linux virtual
+machine.
+
+.. image:: images/VBoxNew.png
+    :align: center
+
+4. Give your new virtual machine a name (it can be anything you want, so long as you can recognize it by its name).
+Make sure that the ``Type`` is set to ``Linux`` and that the version is set to ``Ubuntu (64-bit)``. Then click "Next".
+
+.. image:: images/VBox_VM_name.png
+    :align: center
+
+5. Move the slider for the memory size to the far right of the green section, giving your VM as much memory as you can
+without leaving too little for the host (Windows) OS.
+
+.. image:: images/VBox_memory.png
+    :align: center
+
+6. Create a virtual hard disk to store the data for your Linux VM by selecting ``Create a virtual hard disk now``.
+
+.. image:: images/VBox_create_hard_disk.png
+    :align: center
+
+7. Choose ``VDI`` as the virtual hard disk type.
+
+.. image:: images/VBox_VDI.png
+    :align: center
+
+8. Choose ``Dynamically allocated`` as the storage type, so that your virtual hard disk does not take up more space than
+it needs to.
+
+.. image:: images/VBox_dynamic_storage.png
+    :align: center
+
+9. Set the size of the virtual hard disk to be **no smaller than 50 GB**. If you chose ``dynamically allocated`` in the
+previous step the full 50 GB won't be used initially anyways.
+
+.. image:: images/VBox_disk_size.png
+    :align: center
+
+10. Click on the yellow gear labeled ``Settings``.
+
+.. image:: images/VBox_Settings.png
+    :align: center
+
+11. From the ``System`` menu (left column), go to the ``Processor`` tab and increase the number of CPUs all the way to
+the right side of the green region.
+
+.. image:: images/VBox_cpus.png
+    :align: center
+
+12. From the ``Display`` menu, go to the ``Screen`` tab and max out the video memory.
+
+.. image:: images/VBox_video_mem.png
+    :align: center
+
+13. From the ``Storage`` menu, click on the ``Adds optical drive`` icon (blue circle right next to ``Controller: IDE``
+to add the Ubuntu .iso file to the virtual machine.
+
+.. image:: images/VBox_IDE.png
+    :align: center
+
+.. image:: images/VBox_optical_disk.png
+    :align: center
+
+.. image:: images/VBox_browse_for_disk.png
+    :align: center
+
+.. image:: images/VBox_choose_iso_1.png
+    :align: center
+
+14. Click "OK" to save all of the changes.
+
+.. image:: images/VBox_IDE_complete.png
+    :align: center
+
+15. Click on the green "Start" arrow to begin installing the Linux OS in your virtual machine
+
+.. image:: images/VBox_Start.png
+    :align: center
+
+.. image:: images/VBox_Install_Ubuntu.png
+    :align: center
+
+.. image:: images/VBox_Normal_Install.png
+    :align: center
+
+16. When you get to the page below, choose the option to ``Erase disk and install Ubuntu``. You can safely ignore the
+warning about this deleting all of your programs and data. This warning pertains ONLY to the blank virtual hard disk you
+created earlier. There is nothing you can do here that will delete your data on your host (Windows) system.
+
+.. image:: images/VBox_Erase_Disk_Okay.png
+    :align: center
+
+.. image:: images/VBox_partitions.png
+    :align: center
+
+17. Continue with the installation, choosing a good username (we recommend choosing the same username as the one you use
+on your host OS or for your institution for example) and password (you may optionally select to login automatically on
+startup).
+
+18. After installation is complete, the virtual machine should be up and running. To continue with installing RMG,
+follow the instructions for Linux and Mac OSX systems.
+