Skip to main content

Desktop Installation

BeetleboxCI provides a prebuilt Ubuntu Server 22.04.1 Virtual Machine image to allow users to get started quickly using VirtualBox. This is intended for installing on a desktop PC. If you are installing BeetleboxCI on a server, please refer to the Server Administration section.

System requirements for installing BeetleboxCI::

  • An x64/x86_64/AMD64/Intel 64 system
  • At least 4 CPUs
  • At least 16GB RAM

While it is possible to run BeetleboxCI on a machine with lower CPU and RAM specifications, the above are necessary to achieve good performance. Before installation, we strongly recommend the user to enable hardware virtualisation and disable hypervisor/Hyper-V in the BIOS/UEFI of their machine. You may find the instructions to do this in the user manual of the machine or the user manual of its motherboard. This is necessary to achieve good performance in the BeetleboxCI virtual machine.

You can download the latest version of the BeetleboxCI installer from https://userportal.beetleboxci.com

Windows​

Once you have downloaded and extracted the installer:

  1. Open the executable file (beetleboxci.exe)

  2. Click Install. This will first download the VirtualBox installer and launch the installation wizard.

  3. Once VirtualBox is installed, BeetleboxCI will begin downloading the Virtual Machine image. This is a large file (~6GB) so this will take some time.

  4. BeetleboxCI will then automatically import the downloaded image into VirtualBox

  5. Installation complete! You will need to restart your machine.

  6. After restarting, please reopen beetleboxci.exe

  7. You can now start BeetleboxCI by clicking run.

  8. Once the BeetleboxCI VM boots, open a browser on your host machine and navigate to http://127.0.0.1:32767. If the URL does not work, please wait 5 minutes since the BeetleboxCI app may still be warming up.

  9. If you are accessing the app for the first time, you will be prompted to create a superuser (administrator) account. You can log in once you create the superuser account.

  10. Optionally, if you wish to issue shell commands to the VM (for whatever reason), you can either directly type shell commands into the terminal of the VM or you can SSH into the VM from the host machine using the following command - the username is work1 and the password is password 

    ssh -p 2522 work1@127.0.0.1

    The VM has port forwarding set up such that any SSH connections from the host machine to itself (127.0.0.1) on port 2522 are forwarded to the VM. Similarly, any HTTP connections from the host to itself (127.0.0.1) on port 32767 are forwarded to the VM.

Linux​

  1. Open a terminal and execute ./beetleboxci.bin to open the launcher. Note that for installation, it is mandatory to open the launcher from a terminal rather than from a file browser. For subsequent use, opening from the file browser would be sufficient.

  2. Click Install. This will first download the VirtualBox installer and start the installation. You may be prompted for a sudo password in the terminal window.

  3. Once VirtualBox is installed, BeetleboxCI will begin downloading the Virtual Machine image. This is a large file (~6GB) so this will take some time.

  4. BeetleboxCI will then automatically import the downloaded image into VirtualBox

  5. Installation complete! You will need to restart your machine.

  6. After restarting, please rerun beetleboxci.bin.

  7. You can now start BeetleboxCI by clicking run.

  8. Once the BeetleboxCI VM boots, open a browser on your host machine and navigate to http://127.0.0.1:32767. If the URL does not work, please wait 5 minutes since the BeetleboxCI app may still be warming up.

  9. If you are accessing the app for the first time, you will be prompted to create a superuser (administrator) account. You can log in once you create the superuser account.

  10. Optionally, if you wish to issue shell commands to the VM (for whatever reason), you can either directly type shell commands into the terminal of the VM or you can SSH into the VM from the host machine using the following command - the username is work1 and the password is password 

    ssh -p 2522 work1@127.0.0.1

    The VM has port forwarding set up such that any SSH connections from the host machine to itself (127.0.0.1) on port 2522 are forwarded to the VM. Similarly, any HTTP connections from the host to itself (127.0.0.1) on port 32767 are forwarded to the VM.

Updating the BeetleboxCI VM​

We recommend that you only perform updates while there are no jobs running in BeetleboxCI, as the update will interrupt any jobs that are currently running.

  1. When you open the launcher, you may be notified that an update is available.
  2. Click the Update button to begin the update. This will start the VM (if it isn't already running) and download the updates directly to the VM.
  3. You will be notified when the update has completed and you are now ready to use the latest version of BeetleboxCI.

Manual Installation​

There are some cases where the automatic installation of BeetleboxCI may fail, and it would require a manual installation of VirtualBox and/or a manual import of the Virtual Machine image.

Manual VirtualBox Installation​

If the automatic installation of VirtualBox fails, you can download and install the latest version of VirtualBox at the following link:

VirtualBox

Once you have manually installed VirtualBox, you can retry the steps above for Windows or Linux depending on which OS you are using. The BeetleboxCI Launcher should automatically detect that VirtualBox is installed.

Manual Virtual Machine Image Import​

If the automatic download and/or import of the VM image fails, you can download the latest BeetleboxCI VM image at the following link:

BeetleboxCI VM Image

  1. Open VirtualBox and Click File > Import Appliance

  2. Select Local File System as the source, and browse to the place where you saved the VM image. Click Next

  3. Now you will see the appliance settings. Most of the settings can be kept as they are, but you may wish to change the "Machine Base Folder" setting to a different location if you want the settings and virtual disk of the machine to be stored somewhere other than the default location.

  4. Click Import. This will take some time.

  5. Once the machine has been imported, you may need to change the memory and CPU settings of the VM depending on the specifications of the computer which you are using. Select the machine in the left hand column and click the settings button at the top to open the settings window.

  6. Select the "System" option in the settings window.

  7. On the Motherboard tab, you will need to adjust the slider to reduce the amount of memory allocated to the VM, if the slider is currently in the red region. Similarly, on the Processor tab, you will need to reduce the number of CPUs if the slider is currently in the red region. If the sliders are already in the green region, it is not necessary to adjust them. This can be changed again later.

  8. Now you can run the machine, either directly from VirtualBox or preferably from the BeetleboxCI Launcher. Open the BeetleboxCI launcher and click run (the launcher should automatically detect the existence of the VM, if it is present in VirtualBox). The VM may take a while to boot up.

  9. To access the BeetleboxCI webapp, open a browser on your host machine and navigate to http://127.0.0.1:32767. If the URL does not work, please wait 5 minutes since the BeetleboxCI app may still be warming up.

  10. If you are accessing the app for the first time, you will be prompted to create a superuser (administrator) account. You can log in once you create the superuser account.

  11. Optionally, if you wish to issue shell commands to the VM (for whatever reason), you can either directly type shell commands into the terminal of the VM or you can SSH into the VM from the host machine using the following command (the username is work1 and the password is password as mentioned in step 9): 

    ssh -p 2522 work1@127.0.0.1

    The VM has port forwarding set up such that any SSH connections from the host machine to itself (127.0.0.1) on port 2522 are forwarded to the VM. Similarly, any HTTP connections from the host to itself (127.0.0.1) on port 32767 are forwarded to the VM.