diff --git a/doc/changes/changes_1.1.0.md b/doc/changes/changes_1.1.0.md index 813ef8d3..2ff89314 100644 --- a/doc/changes/changes_1.1.0.md +++ b/doc/changes/changes_1.1.0.md @@ -27,6 +27,7 @@ n/a ## Documentation * 204: Updated developer guide +* #219: Described Virtual Box setup in user guide ## Refactoring diff --git a/doc/developer_guide/aws.md b/doc/developer_guide/aws.md index 5079cf69..ea7f1345 100644 --- a/doc/developer_guide/aws.md +++ b/doc/developer_guide/aws.md @@ -62,7 +62,7 @@ The bucket has private access. In order to control access, the Bucket cloudforma The following diagram shows the involved cloudformation stacks: ![image info](./img/cloudformation-stacks.drawio.png) -The following resources are permanent and need to be deployed using the "deploy" [commands](#deployment-commands): +The following resources are permanent and need to be deployed using the "deploy" [commands](commands.md#deployment-commands): * `DATA-SCIENCE-SANDBOX-VM-Bucket` * `DATA-SCIENCE-SANDBOX-CI-TEST-CODEBUILD` * `DATA-SCIENCE-SANDBOX-RELEASE-CODEBUILD` diff --git a/doc/user_guide/editions.md b/doc/user_guide/editions.md index a8b96379..460be385 100644 --- a/doc/user_guide/editions.md +++ b/doc/user_guide/editions.md @@ -10,11 +10,11 @@ Recommendations * When you want to use the VM Edition then select an appropriate VM image format depending on the Hypervisor software available on your system. -| Description | Format(s) | -|------------------------------------------|--------------------------------------------------------------------------| -| [AMI Edition](ami-usage.md) | Amazon Machine Image (AMI) | -| [Docker Edition](docker/docker-usage.md) | Docker Image | -| [Virtual Machine Edition](vm-usage.md) | VMware Virtual Machine Disk (VMDK), Virtual Hard Disk by Microsoft (VHD) | +| Description | Format(s) | +|---------------------------------------------------|--------------------------------------------------------------------------| +| [AMI Edition](ami-usage.md) | Amazon Machine Image (AMI) | +| [Docker Edition](docker/docker-usage.md) | Docker Image | +| [Virtual Machine Edition](vm-edition/vm-usage.md) | VMware Virtual Machine Disk (VMDK), Virtual Hard Disk by Microsoft (VHD) | Each of the editions is associated with an _image_ in a specific format. diff --git a/doc/user_guide/img/tutorial-screenshot-create-img.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-create-img.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-create-img.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-create-img.png diff --git a/doc/user_guide/img/tutorial-screenshot-importing.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-importing.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-importing.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-importing.png diff --git a/doc/user_guide/img/tutorial-screenshot-open-preferences.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-open-preferences.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-open-preferences.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-open-preferences.png diff --git a/doc/user_guide/img/tutorial-screenshot-select-resources.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-select-resources.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-select-resources.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-select-resources.png diff --git a/doc/user_guide/img/tutorial-screenshot-select-template.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-select-template.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-select-template.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-select-template.png diff --git a/doc/user_guide/img/tutorial-screenshot-show-ip.png b/doc/user_guide/vm-edition/img/tutorial-screenshot-show-ip.png similarity index 100% rename from doc/user_guide/img/tutorial-screenshot-show-ip.png rename to doc/user_guide/vm-edition/img/tutorial-screenshot-show-ip.png diff --git a/doc/user_guide/vm-edition/img/win-vbox/1.png b/doc/user_guide/vm-edition/img/win-vbox/1.png new file mode 100644 index 00000000..f2902478 Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/1.png differ diff --git a/doc/user_guide/vm-edition/img/win-vbox/2.png b/doc/user_guide/vm-edition/img/win-vbox/2.png new file mode 100644 index 00000000..05c38026 Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/2.png differ diff --git a/doc/user_guide/vm-edition/img/win-vbox/3.png b/doc/user_guide/vm-edition/img/win-vbox/3.png new file mode 100644 index 00000000..c56d435a Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/3.png differ diff --git a/doc/user_guide/vm-edition/img/win-vbox/4.png b/doc/user_guide/vm-edition/img/win-vbox/4.png new file mode 100644 index 00000000..c180708c Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/4.png differ diff --git a/doc/user_guide/vm-edition/img/win-vbox/5.png b/doc/user_guide/vm-edition/img/win-vbox/5.png new file mode 100644 index 00000000..2ac3ef02 Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/5.png differ diff --git a/doc/user_guide/vm-edition/img/win-vbox/6.png b/doc/user_guide/vm-edition/img/win-vbox/6.png new file mode 100644 index 00000000..b1d702eb Binary files /dev/null and b/doc/user_guide/vm-edition/img/win-vbox/6.png differ diff --git a/doc/user_guide/vm-usage.md b/doc/user_guide/vm-edition/qemu.md similarity index 51% rename from doc/user_guide/vm-usage.md rename to doc/user_guide/vm-edition/qemu.md index 3cbb4f5b..347d8fc4 100644 --- a/doc/user_guide/vm-usage.md +++ b/doc/user_guide/vm-edition/qemu.md @@ -1,31 +1,10 @@ -# AI-Lab Virtual Machine Edition - -The AI-Lab Virtual Machine Edition offers two different VM images -* VMware Virtual Machine Disk (VMDK) -* Virtual Hard Disk by Microsoft (VHD) - -The following table shows which Hypervisor supports which image formats: - -| Hypervisor | VMDK | VHD | -|---------------------|------|-----| -| VMWare work station | yes | ? | -| Virtual box | yes | yes | -| Hyper-V | ? | yes | -| WSL 2 | ? | ? | - -Notes for Hypervisors based on KVM/[QEMU](https://en.wikipedia.org/wiki/QEMU): -* There multiple alternative UIs, see https://en.wikipedia.org/wiki/Libvirt#User_Interfaces. -* File in format VHD or VMDK needs to be converted first, see - * https://docs.openstack.org/image-guide/convert-images.html - * https://linux.die.net/man/1/qemu-img - ## Boxes (QEMU) on Linux operating system ### Overview 1. Open the `VMDK` image 2. Select Ubuntu 20.04 LTS as template -3. [Configure RAM](system-requirements.md) +3. [Configure RAM](../system-requirements.md) 4. Start the VM ### Step-by-step @@ -42,15 +21,10 @@ Notes for Hypervisors based on KVM/[QEMU](https://en.wikipedia.org/wiki/QEMU): ![image info](./img/tutorial-screenshot-select-resources.png) 8. The image will be imported and then will automatically start ![image info](./img/tutorial-screenshot-importing.png) -9. See section [Login](#login) about how to login +9. See section [Login](vm-usage.md#login) about how to login 10. If you want to connect to the Jupyterlab, you need to find out the IP address of the VM: - Click the 3 dots in Boxes, then preferences
![image info](./img/tutorial-screenshot-open-preferences.png) - Then the IP address will be shown:
![image info](./img/tutorial-screenshot-show-ip.png) -- Use _IP-Address_:49494 to connect to the [Jupterlab](jupyter.md#open-jupyter-in-your-browser) - - -## Login - -See [Log in to AMI and VM Editions](login-vm-and-ami.md) for logging into the system. +- Use _IP-Address_:49494 to connect to the [Jupterlab](../jupyter.md#open-jupyter-in-your-browser) diff --git a/doc/user_guide/vm-edition/vm-usage.md b/doc/user_guide/vm-edition/vm-usage.md new file mode 100644 index 00000000..6ef7a081 --- /dev/null +++ b/doc/user_guide/vm-edition/vm-usage.md @@ -0,0 +1,29 @@ +# AI-Lab Virtual Machine Edition + +The AI-Lab Virtual Machine Edition offers two different VM images +* VMware Virtual Machine Disk (VMDK) +* Virtual Hard Disk by Microsoft (VHD) + +The following table shows which Hypervisor supports which image formats: + +| Hypervisor | VMDK | VHD | +|---------------------|------|-----| +| VMWare work station | yes | ? | +| Virtual box | yes | yes | +| Hyper-V | ? | yes | +| WSL 2 | ? | ? | + +Notes for Hypervisors based on KVM/[QEMU](https://en.wikipedia.org/wiki/QEMU): +* There multiple alternative UIs, see https://en.wikipedia.org/wiki/Libvirt#User_Interfaces. +* File in format VHD or VMDK needs to be converted first, see + * https://docs.openstack.org/image-guide/convert-images.html + * https://linux.die.net/man/1/qemu-img + +## Instructions for specific operating systems and hypervisors + +* [Boxes (QEMU) on Linux operating system](qemu.md) +* [Importing image format VMDK into Oracle Virtual Box on Windows](win-vbox.md) + +## Login + +See [Log in to AMI and VM Editions](../login-vm-and-ami.md) for logging into the system. diff --git a/doc/user_guide/vm-edition/win-vbox.md b/doc/user_guide/vm-edition/win-vbox.md new file mode 100644 index 00000000..07b4771a --- /dev/null +++ b/doc/user_guide/vm-edition/win-vbox.md @@ -0,0 +1,50 @@ +# Importing image format VMDK into Oracle Virtual Box on Windows + +## Preparation + +* [Download the VMDK image file](https://github.com/exasol/ai-lab/releases) for the latest version of the AI-Lab VM Edition +* Download Oracle Virtual Box +* Start Windows application _Oracle Virtual Box_ + +## Select Virtual machine Name and Operating System + +* Create a new virtual machine +* Enter a name for your virtual machine, e.g. "Exasol-AI-Lab-1.0.0" +* Select a folder to store the VM image to +* Select operating system "Linux", e.g. version "Ubuntu 22.04" +* Click button "Next" + +![](img/win-vbox/1.png) + +## Select Hardware + +* Select Base Memory > 8000 MB +* Select > 2 CPUs +* Click button "Next" + +![](img/win-vbox/2.png) + +## Select Virtual Hard disk + +* Select "Use an Existing Virtual Hard Disk File" +* Select the path to the AI-Lab vmk image file + +![](img/win-vbox/3.png) + +## Review Summary + +![](img/win-vbox/4.png) + +## Adjust Network Settings in Oracle Virtual Box Manager + +* Check "Enable Network Adapter" +* For "Attached to" select "NAT" +* Select your Adapter Type, MAC Address, and maybe "Cable Connected" +* Click button "Port Forwarding" +* Forward port 49494 or the virtual machine to the same or any other free port on your Host machine + +![](img/win-vbox/5.png) + +## Run the Virtual Machine + +![](img/win-vbox/6.png)