KB: Vagrant tips
Vagrant is a tool that allows for quickly spinning up virtual machine guests. Yombo uses this tool to install Yombo Gateway on operating systems where:
- The user wishes to isolate the Yombo Gateway installation on Linux.
- The user is on Windows or MacOS .
- The user wishes to develop in an isolated environment, but quickly see those changes.
Working with Vagrant
When running the provision script or running the vagrant command, be sure you are in the yombo-gateway/virtualization/vagrant directory.
Create the Vagrant VM
This will download the Ubuntu image and start the VirtualBox and internally start the installation process of Yombo Gateway requirements. This process might take up to 30 to 40 minutes, depending on internet speed and workstation resources. After the installation is complete, you can access the web interface from the local computer using http://localhost:18080 or using the public ip address (which will be shown when the process is complete).
$ ./provision.sh setup
$ ./provision.bat setup
To get various status of the machine, such as IP address and URLs:
$ ./provision.sh status
Windows (this feature hasn't been implemented yet):
$ ./provision.bat status
Starting / Stopping Guest
To start the guest:
$ ./provision.sh start
$ ./provision.bat start
To stop it:
$ ./provision.sh stop
$ ./provision.bat stop
Connecting to guest
After the guest box has been created by using provision.sh (see also: Vagrant usage), the guest can be accessed in the following ways:
For all hosts
- From within the virtualization/vagrant directory, type: 'vagrant ssh'
- This will ssh directly to the guest.
For MacOS and Linux hosts
- From within the virtualization/vagrant directory, type: './provision.sh status'
- This will provide you the IP address information in order to SSH directly the guest.
- Note: The username and password is: vagrant
Tweaking the machine
The following items can be easily changed:
- RAM - Adjusting the ram available to the guest can give it a small performance boost.
- Default: 1024 (1gb)
- For lightly used systems, 1gb is plenty. When using 250 devices or less and don't need to maintain large device state history in memory.
- If you wish to maintain more device history or more devices, a small memory bump to 1.5gb (1536) all that is needed.
- For very large systems handling more than 500 devices with large device state history, 2gb is plenty.
- For systems wishing to have even longer device state history, 4 to 6GB will be fine.
- Note: The gateway is aware of the system memory and will automatically adjust how much history will be stored in memory for each device.
- CPU - The Vagrantfile script will automatically determine the number of cores based on the machine's physical cores, however, it will only allow up to 4 cores to limit system resources.
- Yombo Gateway is a multi-threaded application and can make use of additional cores.
- Other tools that Yombo Gateway uses are typically multi-threaded as well and can make use of additional cores.
- The Yombo Gateway has been designed to run on Raspberry Pi or other low end hardware and does not require a highly powerful system. However, it will make use of additional hardware if it's available.
- CPU loads are greatest when the Gateway software is being installed or starting up. After this, the CPU should greatly reduce, however, this can depend on what modules are installed.
Before guest is created
Settings before the guest are created are modified in the file Vagrantfile inside the 'virtualization/vagrant'.
- RAM - Look for 'h.memory' and 'h.maxmemory'. Set this to the number of megabytes you wish to use. The default is 1GB (1024).
- CPUs - Replace all $systemCPU entries with the number of cores desired. For example: 'vb.cpus = 3'
After guest is created
- Open the VirtualBox management software.
- If the guest yombo_gateway1084 (or similar) is running:
- Right click on it, click on 'Close', then 'ACPI Shutdown' to gracefully shutdown the guest.
- After a moment, it'll stop and you'll be able to continue.
- Right click on the guest name, then select settings.
- From here, you'll be able to adjust the CPU and memory settings. You can try allocating more or less RAM and/or CPUs. These settings can be adjusted again until you've determined the optimal use for your requirements.