# Elemento Demo - Handbook
## Introduction
**Welcome!**
In this demo you'll be able to experience the new virtualization platform created by Elemento.
The demo tries to mimic the same setup you would get with **one on-premise server** and **one client machine**.
The **Server** is defined as a machine running one copy of our Hypervisor **AtomOS**.
The **Client** can be any runner of our **App Electros**, such as:
* A separate VM (**like in this demo**)
* A physical machine (Linux, Macos, Windows)
* Electros running as a webapp through containers
Additionally, our **App Electros** provides both a GUI written in React and a CLI written in Python and available on the terminal of the Client machine.
**Let's get started!**
## Loggin in
Within this demo you'll get access to three distinct webpages: two are the administrative back-ends on both the **Server** and the **Client**, the latter is our **App Electros** deployed as WebUI.
Hereafter you'll find all you need to make use of these!
### Electros WebUI
In order to make use of your **Elemento Demo**, you'll need an **Elemento User Account**.
To create one you can head to [this page](https://www.elemento.cloud/forms/sign-in).
Your account will be promptly created and a confirmation email will be sent to you, along with a link to **setup your password**.
:::info
Did you forget your password?
Just head to [this link](https://portal.elemento.cloud/password_recovery) to recover it.
:::
From now on your Elemento User Account will be ready for use at [this page](http://4.232.138.231:3000) (Demo Client WebUI).
:::success
The WebUI mimics a **single user Electros App**, therefore opening the same page from multiple machines will keep the **same account logged in**, since the logged account information is **stored server-side**.
:::
### Cockpit Sysadmin Dashboard and SSH
If required, Elemento's Demo team will share with you a Unix account which you'll be able to use to do connect in two different ways:
* Use SSH towards either the **Server** or **Client** machine
* Use the back-end Sysadmin WebUI (Cockpit) available on both **Server** and **Client**
The AtomOS **Server** Sysadmin Dashboard is available [here](https://4.232.130.233:9090).
:::warning
**Please note**: this kind of access might not be granted for the sake of your specific Elemento Demo, unless required in advance providing some motivations.
We can even enable **SSH access** upon request. Don't be shy!
:::
## Useful links
### [Demo Client Electros WebUI](http://4.232.138.231:3000)
### [Demo Client Sysadmin Dashboard](https://4.232.138.231:9090)
### [Demo Server Sysadmin Dashboard](https://4.232.130.233:9090)
:::info
The WebUI is hosted on a **unsecure http** endpoint and communication between the Demo **Server** and **Client** are **not encrypted**, therefore we do not recommend performing any sensible activity related with sensible data.
In addition, the Demo cluster is often completely erased and data volumes get deleted every now and then.
:::
## Your first VM: Step-by-step
All operations can be performed through the **Electros WebUI** or **Electros CLI**. Below you'll find a detailed guide for either of the two.
### Electros WebUI
The WebUI will be available [here](http://4.232.138.231:3000/).
#### Step 0: Login with Elemento User Account
You'll need to input your Elemento User Account credentials, to be greeted with the welcome screen:
At this point you'll be ready to step to the juicy parts!
#### Step 1: Create some volumes
In order to create your first VM, you'll first need to allocate some storage volumes.
The first one you'll need is a **bootable** volume to later install an OS on for your VM. In order to create such volume you can head to the **Storage** section.
Depending on previous operations by either you or Elemento's team, you might find some volumes already present.
To create a new one click on "Create new storage" and make your choices according to the following parameters:
* **Name** of the volumes
* **Size** of the volume (with unit of measure GB or TB)
* **Private** true/false to limit the access to the volume to you and you only
* **Shareable** true/false to allow the volume to be connected to multiple VMs at once
* **Bootable** true/false to mark the volume as a valid option for an OS install
* **Readonly** true/false to limit write access to the volume
Usually you'll start with a **bootable** volume to install your VM OS on. To do so use the following settings:
If you feel adventurous you can create additional volumes to play around!
#### Step 2: Create your VM
Once you're satisfied with your volumes, head to the **Virtual Machines** section to allocate your computing resources and create your VM.
Click on "Create new virtual machine".
Now you have two options: keeping it **simple** or making it **advanced**!
##### Automagic: Use a VM template
The **Automagic** procedure will simplify the VM creation allowing an easy selection of **predefined templates**.
Such templates are standard setups ready to be used and contain some specifications on CPU, RAM and GPUs.
Pick a VM name, a template and an OS flavor and then, finally, select from the "Storage Selection" dropdown one or more volumes and click on "Mount" for each of them.
Once done, the right side summary will appear with a "Confirm and create" button. Click on it and allocate your VM.
:::warning
**Please note**: the machine reserved for the Demo session **has no GPU installed**, therefore no template or configuration involving a GPU will be allocated.
:::
##### Advanced: Make it your way
The advanced procedure allows one to setup a tailor-made VM through a bunch of steps.
You'll be able to choose the CPU configuration, the RAM amount and kind, the volumes and GPUs to be attached to the VM.
All of the steps are organized in a wizard to guide you through.
<img src="https://hackmd.io/_uploads/B1Mf4XjwA.jpg" width="50%"/>
<img src="https://hackmd.io/_uploads/SJNGNQowA.jpg" width="50%"/>
<img src="https://hackmd.io/_uploads/HJ4zEQjPR.jpg" width="50%"/>
<img src="https://hackmd.io/_uploads/BkVzVQsPA.jpg" width="50%"/>
<img src="https://hackmd.io/_uploads/ByVzE7iw0.jpg" width="50%"/>
<img src="https://hackmd.io/_uploads/rJNf4XiPC.jpg" width="50%"/>
Finally you'll reach the Summary page, from which you'll be able to finally allocate your VM.
For the sake of the Demo, only the specific **Server** running AtomOS is available, therefore it is automatically selected.
In a real case scenario you would be able to select a specific host or just click *continue* to let the system choose the best one.
:::success
**Please note**: an Ubuntu ISO image is already available on the Demo **Server** and selecting Linux Ubuntu as OS flavor will automatically mount the ISO image as boot drive to proceed with the initial setup.
:::
:::danger
**Please note**: the resources provided for the Demo are limited: once all resources have been assigned to the VMs, additional allocations will fail.
The Demo **Server** provides 8 CPU cores, 15GB of RAM and 1000GB of storage.
**Try deleting some VMs to free up some juice!**
:::
### Electros CLI
In order to create Volumes and VMs through the CLI you can either connect to a bash terminal on the **Client** machine [at this page](https://4.232.138.231:9090/system/terminal) using the Unix Login or you can [download and install Electros CLI](https://www.elemento.cloud/electros-download) on your private machine.
Open the following details section to discover how to setup your private **Client** machine to operate on the Demo **Server**.
:::spoiler
In order to make your local Electros CLI on your private machine able to operate on the Demo infrastructure, you have to edit two specific files on your machine.
The first is `~/.elemento/hosts` to include the Demo **Server** public IP address:
```hostfile=
4.232.130.233
```
The second is `~/.elemento/settings` to make the CLI connect to the Demo **Server**:
```json=
{
"useDiscovery": false,
"useTCPList": true
}
```
Once done restart your local Elemento Daemons to make the edits loaded.
:::
In this example we'll assume you already have a working install of Electros CLI.
#### Step 0: Login with Elemento User Account
Use the following command to login into your Elemento User Account:
```bash
$: elemento auth login
You are not logged in
Write username
testdrive@elemento.cloud
Write password
Password: ≡≡≡≡≡≡≡≡
Login successful
```
#### Step 1: Create some volumes
Volumes creation through the CLI simply requires inputting the volume details as arguments to the `elemento volume create` command.
In particular, the `--size` argument specifies the desired allocated space.
All the additional attributes can be passed as a `json` file through the `--spec-json` parameter.
An example `volume.json` file for a typical bootable volume is the following:
```json
{
"name": "my-bootable-volume",
"bootable": true,
"shareable": false,
"private": true,
"readonly": false
}
```
Where:
* **`name`** of the volume
* **`private`** true/false to limit the access to the volume to you and you only
* **`shareable`** true/false to allow the volume to be connected to multiple VMs at once
* **`bootable`** true/false to mark the volume as a valid option for an OS install
* **`readonly`** true/false to limit write access to the volume
The complete command is:
```bash
$: elemento volume create --size 50 --json-spec volume.json
b1922e8d8b0c4ff1be46345e4c8ae546
```
Which will output a VolumeID (in this case `b1922e8d8b0c4ff1be46345e4c8ae546`) to be used as an handle to attach such volume to VMs.
By using different parameters you'll be able to create volumes with different settings.
In order to list all available volumes, one would run:
```bash
$: elemento volume list
```
#### Step 2: Create your VM
In order to define the VM and its attached volumes, you would need to create two `json` files, one for the compute resources and one to define the volumes to be attached.
The file `vmspec.json` can contain many parameters.
An example of a valid `vmspec.json` follows:
```json
{
"slots": 2,
"overprovision": 2,
"allowSMT": false,
"archs": ["X86_64"],
"flags": ["sse2"],
"min_frequency": 1.5,
"ramsize": 2048,
"reqECC": false,
"misc": {"os_family": "linux", "os_flavour": "ubuntu"}
}
```
The `volumes.json` file, instead, simply contains the VolumeIDs of the volumes to attach:
```json
[
{"vid":"b1922e8d8b0c4ff1be46345e4c8ae546"},
{"vid":"23cc122380924c9babfc23210e0a0d16"}
]
```
Such files are combined into a single command to allocate a new VM:
```bash
$: elemento vm create --spec-json vmspec.json --volume-json volumes.json
```
To list the running VMs simply run:
```bash
$: elemento vm list
```
#### Step 3: Advanced use
To get additional information on how to fully use Elemento CLI please head to [this page](https://hackmd.io/@elementomc/SyB3e5ikh).
## Use your VM
At the moment Elemento does not include a direct connection to the VMs before the initial OS setup.
This means the install procedure must be accomplished using the sysadmin dashboard.
In order to access your VM to complete the OS setup head to [this page](https://4.232.130.233:9090/machines) on the **Server**.
Here you can find all the allocated VMs.
The VM names in this view correspond to the VM IDs found in Electros.
Clicking on the VM name you'll reach a detailed view which sports a direct video connection to the VM from which you'll be able to interact with your OS installer.
Many OSes **do not enable by default** remote connection protocols, such as **SSH**, **VNC** or **RDP**.
From this page you'll always be able to enable such protocols in order to enable direct connection to the VM through other tools.
## Elemento Shared volumes
We introduced **experimental** support for volumes shared between VMs.
Such volumes must be created with the `shareable` attribute set to `true` and can be attached to more than one VM at once.
Such functionality is nowadays limited to **one shared volume** per VM.
In order to mount the shared volume inside the VM one should get the "Mount tag" of the shared volume from the Sysadmin dashboard:
In order to mount such volume in a Linux VM one should run:
```bash
mount -t virtofs 0x7d5abd86ac881faf21207f776d9d8d4e /mnt/shared-data
```
Where `0x7d5abd86ac881faf21207f776d9d8d4e` is the "Mount tag".
On Windows VMs such functionality is achievable using the `virtio-guest-tools`, to be installed separately.
## Elemento Demo and Networking
Within the Demo infrastructure our VMs will be granted Internet access, but their IPs won't be exposed.
This is caused by the specific setup and is enforced by security reasons.
In the complete Enterprise version of AtomOS, when installed on a physical server, the VMs will get a new IP on the DHCP baking their upstream (virtual)switch.
As a workaround, in case you got a Unix account, you can retrieve the local IP address of the VM from the sysadmin dashboard and connect to it via SSH/VNC/RDP through a local SSH tunnel going through the Demo **Server**.
Given the VM's IP in the above example is `192.168.1.1` and the Demo **Server** IP is `4.232.130.233`, the SSH tunnelling for SSH, VNC and RDP are:
* **SSH**:
```ssh -L <local port>:<VM IP address>:22 <Server IP address>```
therefore
```ssh -L <local port>:192.168.1.1:22 4.232.130.233```
where `<local port>` must have no conflict with currently in-use ports.
* **VNC**:
```ssh -L <local port>:<VM IP address>:5900 <Server IP address>```
therefore
```ssh -L <local port>:192.168.1.1:5900 4.232.130.233```
where `<local port>` must have no conflict with currently in-use ports.
* **RDP**:
```ssh -L <local port>:<VM IP address>:3389 <Server IP address>```
therefore
```ssh -L <local port>:192.168.1.1:3389 4.232.130.233```
where `<local port>` must have no conflict with currently in-use ports.
Once done SSH, VNC or RDP can be accessed from the machine the SSH tunnel has been set up at `localhost:<local port>`
Sign in with Wallet
Connect another wallet