Automated Virtual Installation

This automated installer provides you with an easy way to install StarlingX r9.0 in different configuration options in a virtual environment.

Physical host requirements and setup

This section describes how to prepare the physical host and virtual environment for an automated StarlingX r9.0 virtual deployment in VirtualBox.

The following sections describe the system requirements and host setup for a workstation hosting virtual machine(s) where StarlingX will be deployed.

Hardware requirements

The host system should have at least:

  • Processor: x86_64 only supported architecture with BIOS enabled hardware virtualization extensions

  • Cores: 8

  • Memory: 32GB RAM

  • Hard Disk: 500GB HDD

  • Network: One network adapter with active Internet connection

Software requirements

The host system should have at least:

  • A workstation computer with Ubuntu 20.04 LTS 64-bit

Host setup

Set up the host with the following steps:

  1. Update OS and install dependencies:

    apt-get update
    sudo apt install -y virtualbox socat git rsync sshpass openssh-client python3-pip python3-venv
  2. Clone the StarlingX tools repository:

    cd $HOME
    git clone
  3. Set up Python’s Virtual Environment:

    cd $HOME/virtual-deployment/virtualbox/pybox
    python3 -m venv venv
    source ./venv/bin/activate
    pip install --upgrade pip
    pip install -r requirements.txt
  4. Create NatNetwork:

    VBoxManage natnetwork add --netname NatNetwork --network --dhcp off --ipv6 on
  5. Get the StarlingX ISO:

    wget -O $HOME/Downloads/stx-8.iso
  6. Create a local copy of the config file templates.

    cp -r config myconfig

    Make the desired changes in the config files on the new directory.


This setup guide can be found in the file in $HOME/virtual-deployment/virtualbox/pybox

Installation Configurations

The configurations available from this script, via the --setup-type parameter, are:

  • AIO-SX or “All-In-One Simplex” will set up one single VM that will be both a controller and a worker node.

  • AIO-DX or “All-In-One Duplex” will set up two controller VMs with one of them also being a worker.

  • STANDARD setup is currently under review.

  • STORAGE setup is currently under review.

Deployment Example


The following commands are an example on how to run the script for the deployment of an All-In-One Simplex configuration.

  1. Set the password for the StarlingX system

    export STX_INSTALL_PASSWORD=<password>

    The script validates the password as it must contain:

    • Minimum of 7 characters.

    • At least 1 uppercase letter.

    • At least 1 number.

    • At least 1 non-alphanumeric character.

  2. Run the script

    cd $HOME/virtual-deployment/virtualbox/pybox
    source ./venv/bin/activate
    python3 ./ \
    --setup-type <AIO-SX/AIO-DX> \
    --iso-location "$HOME/Downloads/stx-8.iso" \
    --labname StarlingX --install-mode <serial/graphical> \
    --config-files-dir ./myconfig/labSetupFiles/ \
    --ansible-controller-config ./myconfig/ansibleFiles/<simplex/duplex>_localhost.yml \
    --kubernetes-config-files ./myconfig/kubeFiles/ \
    --vboxnet-type nat \
    --vboxnet-name NatNetwork \
    --nat-controller0-local-ssh-port <PORT_CONTROLLER0> \
    --nat-controller1-local-ssh-port <PORT_CONTROLLER1> \
    --password $STX_INSTALL_PASSWORD


All available configuration options can be found using --help. Parameters as --snapshot and --headless may be beneficial if working in a development environment.


The localhost.yml file can be modified for further configurations during the Ansible bootstrap, refer to Ansible Bootstrap Configurations for information on additional configurations for advanced Ansible bootstrap scenarios, such as Docker proxies when deploying behind a firewall, etc. Refer to Docker Proxy Configuration for details about Docker proxy settings.


In a machine with the physical host requirements described on this page, the script will take 60 to 90 minutes to be fully completed (from creating a VM and installing an OS to configuring StarlingX). The total amount of time will depend on the deployment configurations. Several restarts will occur, and a VirtualBox window with a prompt may appear.


After the completion of the script your StarlingX cluster is now up and running.


Starlingx Horizon GUI

The script automatically sets up a port-forwarding rule in VirtualBox for accessing the StarlingX Horizon GUI. The default port is 8080, if none was chosen.

Access the StarlingX Horizon GUI with the following steps:


  1. Enter the the following address in your browser: http://localhost:8080.

  2. Log in to Horizon with an admin/<sysadmin-password>.

Kubernetes Dashboard

The script automatically sets up a port-forwarding rule in VirtualBox for accessing the Kubernetes dashboard. The default port is 32000, if none was chosen.


  1. Enter the the following address in your browser: http://localhost:32000.

  2. Log in to the Kubernetes dashboard using the admin-user token.

    The token can be found in the token.txt file sent to $HOME in the host machine.