Installation on Vagrant

From Yombo
< docs‎ | gateway
Jump to: navigation, search

Overview

See also

The Yombo Gateway software can be installed using Vagrant on Linux, Windows, or MacOS. This creates a VirtualBox instance where the Yombo Gateway software, and its dependencies, are installed and configured. This is perfect for isolation, development, or when running on Windows or Mac.

Vagrant is an open-source software product for building and maintaining virtual software development environments. VirtualBox is open-source software that runs a virtual machine on your computer.

If you are setting up Vagrant for develop or contribute to Yombo Gateway: Follow the Setup Development Environment guide instead.

Directory Mapping

The root yombo-gateway will be mirrored to the /yombo-gateway directory on the guest virtual machine. Additionally, the working directory (where Yombo Gateway stores the database, configuration files, and more) will be mapped to yombo-gateway/virtualization/vagrant/working_dir.

Prerequisites

You'll need to fork the Yombo Gateway repository and install some software to get going.

Install Software

You'll need to download and install Vagrant and VirtualBox, as well as the VirtualBox extensions (from the same page as VirtualBox).

Note

When using Ubuntu and derivatives such as Mint or Pop!_OS, be sure to add the vagrant launchpad repository for the latest vagrant version: sudo add-apt-repository ppa:tiagohillebrandt/vagrant


If you don't have git, be sure to install GIT too.

Note

When using GIT on Windows, you need to change git’s auto.crlf value before cloning the Yombo Gateway repository to handle end-of-line formatting between Linux and Windows.

git config --global core.autocrlf input

Download Yombo

Next, download the Yombo Gateway source code. From the directory you wish to install the software:

Download the source code:

$ git clone https://github.com/yombo/yombo-gateway.git

Working with Vagrant

Note

KB:Vagrant tips - Learn more on how to work with Vagrant and the guest machine, such as starting it, stopping it, or recreating it.

When running the provision script or running the vagrant command, be sure you are in the yombo-gateway/virtualization/vagrant directory.

Note

On Windows, Vagrant is controlled through an elevated PowerShell using provision.bat instead of provision.sh.

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).

Linux:

$ cd yombo-gateway/virtualization/vagrant
$ ./provision.sh setup

Windows:

$ cd yombo-gateway/virtualization/vagrant
$ ./provision.bat setup

Get Status

To get various status of the machine, such as IP address and URLs:

Linux:

$ ./provision.sh status

Windows (this feature hasn't been implemented yet):

$ ./provision.bat status

Starting / Stopping Guest

To start the guest:

Linux:

$ ./provision.sh start

Windows:

$ ./provision.bat start

To stop it:

Linux:

$ ./provision.sh stop

Windows:

$ ./provision.bat stop

Connecting to guest

To connect to the guest, use on of the following:

Using vagrant

This must be performed within the 'yombo-gateway/virtualization/vagrant' directory:

$ vagrant ssh

Using SSH

From the 'yombo-gateway/virtualization/vagrant' directory, find the IP address of the guest:

$ ./provision.bat status

Look for the line that states "Network IP Address". You'll use this IP address to connect to the machine. The username and password is vagrant. The below example assumes an IP address of 192.168.1.200 as reported by the vagrant status command.:

$ ssh vagrant@192.168.1.200

Next steps

  • KB:Vagrant_tips - Learn how to interact with Vagrant such as starting/stopping the guest, or recreating the guest.
  • Setup Wizard - Now that installation is done, get running quickly using the setup wizard.
This page was last edited on 17 May 2020.