Holo Internal Testing: Virtual Machine
===

:::danger
If you have already set up an HoloPortOS virtual machine and need to update it for new releases, we would **strongly** prefer that you let the system auto-update rather than downloading a newer copy of the VM. *This helps us to test auto-updates*.

If you have a problem with auto-updating, please use the feedback or bug report categories on forum.holo.host rather than pinging devs through Mattermost. *This helps us to practice our customer service processes*.
:::

To join the Holo network you will need:
1. Your credentials file: `hpos-state.json`
2. An internet-connected computer that can run VirtualBox
3. Magic-Wormhole: A free, open-source tool to send your credentials file to your VM
4. A running HoloPortOS virtual machine

## Creating Your Holo Credentials

Your Holo credentials live in a file called `hpos-state.json`. This contains the information required to generate your keys and needs to be kept securely.

To generate these files, go to https://quickstart.holo.host and follow the steps to generate and download your file.

:::info
These VM instructions supercede the instructions in https://quickstart.holo.host, which are for HoloPorts only. VM users should ignore HoloPort instructions and only use https://quickstart.holo.host to generate the `hpos-state.json` file.
:::

## Setting Up the Virtual Machine

### 1. Download VirtualBox from Oracle

Download virtualbox platform 6.x and install following the instructions here

https://www.virtualbox.org/wiki/Downloads

### 2. Download and install virtual machine

1. Download the latest Holoport Testnet machine
https://hydra.holo.host/build/9024/download/1/holoportos-for-virtualbox.ova
2. Once downloaded, double-click the .ova file, which will launch the process to import the box into VirtualBox
3. On the "Appliance Settings" import page, disable the USB controller checkbox

## Installing Magic-Wormhole
#### macOS
1. Download and install xcode from the mac app store if you haven't done before
2. Install Homebrew by opening the terminal and pasting and running the following command: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
- For more info: https://brew.sh
- Rememember to include the last quotation mark
3. Paste and run the following command: `brew install magic-wormhole`

#### Linux (Ubuntu/Debian)
Run `$ sudo apt install magic-wormhole`

#### Linux (Fedora)
Run `$ sudo dnf install magic-wormhole`

#### Linux (openSUSE)
Run `$ sudo zypper install python-magic-wormhole`

#### Windows
1. Download the latest Python 2.x release at https://www.python.org/downloads/windows/ and install it in the default location
2. Open cmd.exe
3. Paste and run: `pip install --upgrade pip`
4. Paste and run: `pip install magic-wormhole`

Detailed instructions and information can be found here:
https://magic-wormhole.readthedocs.io/en/latest/welcome.html#installation

## Release 1: Initialisation

1. Place your `hpos-state.json` file in the home directory of your computer (not the VM):
- For Mac: `/Users/<username>`
- For Linux:`/home/<username>`
- For Windows Vista, 7, 8, 10:`\Users\<username>`
- For Windows 2000, XP, 2003:`\Documents and Settings\<username>`
2. Click the "start" green arrow on the virtualbox interface (upper right corner) to boot up your VM
3. Once your VM has finished booting, it will broadcast a command that looks something like: `wormhole send --code [pass phrase] --text - < hpos-state.json`
4. In your host computer's terminal (not the VM), type in the full `wormhole send` command to send your credentials file to your VM.
- On Windows you will need to type `python -m wormhole send ...`
- If successful, your host computer's terminal will print: `text message sent`
- Your host computer's terminal may also ask you to run `wormhole receive` on the VM. **Ignore this**
- To confirm that the right credentials were copied to your VM, you can run `cat /etc/hpos-state.json`. This will print out the contents of the hpos-state.json file and you can confirm that the seed string is the same as the one downloaded from quickstart.holo.host
`The system will generate your HC keys.`
4. You will receive an email verification. Follow the instructions.
`The system will now register your Hosting device on the Holo network internal DNS for routing`
5. Success: You can see a non-functional HP Admin page
- __Ignore the security warning. It's because we have not completed certificate signing__
6. Once registered and working, fully shut down your VM
7. Restart your VM
8. Confirm that:
A. You can still access the HP Admin page through the same link to your HoloPort
B. You do not need to go through the initialisation process again
9. Post a success confirmation in the feedback section of forum.holo.host

::: warning
Instructions for step 4 have been left intentionally vague to test the clarity of email UX.
:::

## Release 2: HP Admin UI

::: info
This section TBD
:::

## Release 3: Hosted hApps

::: info
This section TBD
:::