Various improvements + screenshot

README.adoc

 = Ubuntu VM Creator
 
-A set of scripts to create small Ubuntu Desktop (with MATE desktop) virtual machines for Virtual Box.
+A set of scripts to automatically create small Ubuntu Desktop (with MATE desktop) virtual machines for Virtual Box.
+
+image::screenshots/example-customization.png[]
 
 Only tested on a GNU/Linux system (Fedora 33).
 
+WARNING: Make sure you have lots of free space on your computer before running these scripts! At least 50G of free space is required to run the three steps.
 
 == Idea
 
@@ -25,7 +28,7 @@ This is done simply by mounting the raw image and is thus rather fast.
 
 == Step 1: Create a base raw image
 
-Run `create_base_img.sh` to create `output/minimal-ubuntu-base.img`.
+Run `create_base_img.sh` to create `output/mini-ubuntu-base.img`.
 
 This only has to be executed once, but it is rather long, be patient :).
 
@@ -40,16 +43,29 @@ The resulting image has the following characteristics:
 - It contains the _VirtualBox Guest Additions_.
 
 
-== Step 2: Customize the raw image
+== Step 2: Customize the raw image (optional)
+
+To customize a base image, you can run :
 
-Run `customize_base_image.sh <customization folder>` to create `output/minimal-ubuntu-customized.img`.
+```
+customize_base_image.sh <customization_folder_path>
+```
+
+which will create `output/mini-ubuntu-<customization_folder_name>.img`.
 
 A customization folder is any folder on your host that may contain:
 
 - a `files` folder that contains the file hierarchy to be copied as is inside the root (`/`) of the virtual machine image,
-- a `run.sh` bash script that will be executed as `root` in a chroot inside the virtual machine image. 
+- a `run.sh` bash script that will be executed as `root` in a _chroot_ inside the virtual machine image. 
+
+An example customization folder called `example-customization` is provided, which (1) adds a "Hello world" file on the desktop of the user and (2) installs VSCode.
+You can run this example with the command 
 
-An example customization folder called `example-customization` is provided, and can be used with the command `customize_base_image.sh example-customization`.
+```
+customize_base_image.sh example-customization
+```
+
+which will create `output/mini-ubuntu-example-customization.img`.
 
 NOTE: You can re-run this step as many times as needed, eg. to debug a `run.sh` customization script.
 
@@ -58,6 +74,17 @@ NOTE: You can re-run this step as many times as needed, eg. to debug a `run.sh`
 
 == Step 3: Convert to Virtual Box
 
-Run `convert_to_vbox.sh` to create `output/minimal-ubuntu-customized.ova`.
+To convert a raw `.img` image into a usable virtual box image, you can run the following command:
+
+```
+convert_to_vbox.sh <raw_image_path>
+```
+
+which will create :
 
-The resulting image, once compressed in this format, is about 3.7G (without customization), and can be directly imported in any Virtual Box environment.
\ No newline at end of file
+- `output/<raw_image_name>.vdi`: the VBox virtual disk directly obtained from the raw image file,
+- A new VM in your local Virtual Box instance, which uses the `.vdi` file mentioned above. 
+You can run this VM to test the result.
+- `output/<raw_image_name>.ova`: the compressed VBox standalone exported virtual machine (which includes a copy of the virtual disk). 
+This is the final file that can be archived/shared/used, and imported in any Virtual Box instance.
+It's size should be around 3.7G (without customization).
\ No newline at end of file

convert_to_vbox.sh

@@ -4,24 +4,36 @@ set -x
 set -e
 
 
+if [ $# -ne 1 ]; 
+    then 
+    echo "Illegal number of parameters"
+    exit 2
+fi
+
+
+
+# IMG=$OUTPUT_FOLDER/$VM_NAME-customized.img
+IMG=$1
+IMG_BASENAME=$(basename -s .img $IMG)
 OUTPUT_FOLDER=output
-OUTPUT_IMG=$OUTPUT_FOLDER/mini-ubuntu-customized.img
-OUTPUT_VDI=$OUTPUT_FOLDER/mini-ubuntu-customized.vdi
-OUTPUT_OVA=$OUTPUT_FOLDER/mini-ubuntu-customized.ova
+OUTPUT_VDI=$OUTPUT_FOLDER/${IMG_BASENAME}.vdi
+OUTPUT_OVA=$OUTPUT_FOLDER/${IMG_BASENAME}.ova
+VM_NAME=$IMG_BASENAME
 
 
-VBoxManage unregistervm "mini-ubuntu" --delete || true
+VBoxManage unregistervm "$VM_NAME" --delete || true
 
 mkdir -p $OUTPUT_FOLDER
 rm $OUTPUT_VDI || true
 rm $OUTPUT_OVA || true
 
-VBoxManage convertfromraw --format vdi $OUTPUT_IMG $OUTPUT_VDI
-VBoxManage createvm --name "mini-ubuntu" --ostype "Ubuntu_64" --register --basefolder $OUTPUT_FOLDER
-VBoxManage storagectl "mini-ubuntu" --name "SATA Controller" --add sata --controller IntelAhci --portcount 1    
-VBoxManage storageattach "mini-ubuntu" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium  $OUTPUT_VDI                
-VBoxManage modifyvm "mini-ubuntu" \
+VBoxManage convertfromraw --format vdi $IMG $OUTPUT_VDI
+VBoxManage createvm --name "$VM_NAME" --ostype "Ubuntu_64" --register --basefolder $OUTPUT_FOLDER
+VBoxManage storagectl "$VM_NAME" --name "SATA Controller" --add sata --controller IntelAhci --portcount 1    
+VBoxManage storageattach "$VM_NAME" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium  $OUTPUT_VDI                
+VBoxManage modifyvm "$VM_NAME" \
     --boot1 disk --boot2 none --boot3 none --boot4 none \
     --memory 1024 --vram 16 --graphicscontroller vmsvga \
-    --clipboard-mode bidirectional
-VBoxManage export  "mini-ubuntu" --output $OUTPUT_OVA
\ No newline at end of file
+    --clipboard-mode bidirectional \
+    --description "Created on $(date)"
+VBoxManage export  "$VM_NAME" --output $OUTPUT_OVA
\ No newline at end of file

customize_base_image.sh

@@ -11,7 +11,7 @@ if [ $# -ne 1 ];
 fi
 
 CUSTOMIZATION_FOLDER=$1
-# CUSTOMIZATION_FOLDER_BASE=$(basename $CUSTOMIZATION_FOLDER)
+CUSTOMIZATION_FOLDER_BASE=$(basename $CUSTOMIZATION_FOLDER)
 
 
 function cleanup() {
@@ -28,7 +28,7 @@ cleanup
 # Variables
 OUTPUT_FOLDER=output
 BASE_IMG=$OUTPUT_FOLDER/mini-ubuntu-base.img
-CUSTOMIZED_IMG=$OUTPUT_FOLDER/mini-ubuntu-customized.img
+CUSTOMIZED_IMG=$OUTPUT_FOLDER/mini-ubuntu-${CUSTOMIZATION_FOLDER_BASE}.img
 LOOP=$(sudo losetup -f)
 
 # Copy base img if needed