Skip to content

planet-installation-vagrant.md

Latest commit

 

History

History
152 lines (95 loc) · 9.45 KB

planet-installation-vagrant.md

File metadata and controls

152 lines (95 loc) · 9.45 KB

Planet Installation

Objectives

  • Set up an environment for Planet
  • Install Community Planet

Introduction

The Planet is a virtual library that is deployed internationally to individuals in countries that typically do not have access to educational resources.

Please follow the directions of your OS below to install your community Planet and its dependencies on our system.

Prerequisites

Staying Organized

We recommend you designate a new directory for your work at OLE. This puts all of your OLE related repositories in one place and enables you to be organized and efficient.

To do this, you could make a new folder directly through your OS GUI. Or you could open Terminal(macOS or Ubuntu), cmd(Windows) and use the following commands: (Note the commands should be identical on all three operating systems)

cd Desktop
mkdir OLE

Virtualization

Before installing Vagrant on any platform, it is necessary to check if VT-x/AMD-V instruction set is enabled on your processor by checking the BIOS. This is a requirement for installing Vagrant on any platform since Vagrant is a type of virtualization software that utilizes VirtualBox.

Most recent CPUs have this feature enabled already, but if you are unsure whether VT-x/AMD-V is enabled on your device please see the following on Windows | Ubuntu | Mac

If later you are having trouble running Vagrant, it may be that VT-x/AMD-V is not enabled on your system. Here are instructions to enable virtualization on Windows | Ubuntu | macOS

Storage Space

Before installing Vagrant on any platform, it is necessary to have at least 7 GB of free space on your computer. Vagrant and VirtualBox take up approximately 6 GB to 7 GB on your machine, and in order to minimize downloading errors, check to see if you have enough storage space before installation.

  • To check your current storage space on Mac go to the Apple Logo on the top left of your screen, About This mac > Storage
  • To check your current storage space on Windows go to Settings > System > Storage

Windows

Dependencies

You need to install the following programs on your computer:

  • Git Git is an open source version control system that we use for communication and management for our software. More specifically, we use Slack for communication and github.com for software management. Download

  • VirtualBox Virtualbox allows you to install a software virtualization package as an application on your OS. Download

  • Vagrant
    Vagrant is an open source tool for building development environments. Download

NOTE: Due to some issues we are seeing with newest version of vagrant. We suggest you to use vagrant below 2.2.5

macOS or Ubuntu

Preparation

Open your Terminal

For macOS

We assume that brew is already installed:

brew install git
brew cask install vagrant
brew cask install virtualbox

If VirtualBox installation fails, go to System Preferences > Security & Privacy and click Allow. You may need to eject VirtualBox from Finder > Devices and retry multiple times. More information in this thread.

For Ubuntu

sudo apt-get update
sudo apt-get -y install git virtualbox

Next, go to Vagrant download page in Firefox Web browser and Right click on the 64-Bit version of Debian and select "Copy Link Location" from the pop-up menu. Refer to this image:

Debian 64-Bit Download

Now replace https://yourcopiedlink.com/vagrant.deb in the following commands by the link which you just copied.

wget -O vagrant.deb https://yourcopiedlink.com/vagrant.deb
sudo dpkg -i vagrant.deb
sudo apt-get install -f

If you encounter the error:

dpkg: error processing archive vagrant.deb (--install): package architecture (amd64) does not match system (i386) Errors were encountered while processing: vagrant.deb

To solve this problem: Copy link location of Debian 32-bit instead and run commands again.

Install a Community Planet (Windows)

Make sure you cd to the designated OLE directory you created earlier.

git clone https://github.com/open-learning-exchange/planet.git
cd planet
vagrant up prod

You now have a working community Planet on your OS, that can be accessed using http://localhost:3100. It is advisable to use Firefox to access your community Planet. If you don't have Firefox already, you may want to download it. If you are using Firefox and community Planet is not working properly, please update your Firefox to the latest version and then try again.

When the login screen loads, Follow further steps in the Planet Manual to register as a member.

Troubleshooting

  1. On macOS, when you run vagrant up prod, you may experience an error such as the following: "vi: Box 'ole/jessie64' could not be found. Attempting to find and install...". A simple solution is to use this command sudo rm /opt/vagrant/embedded/bin/curl, This will remove the old version of curl in Vagrant and vagrant up should now work as usual. For more information, visit this Stack Overflow question

  2. On Windows, when you run vagrant up prod from command prompt, you might get the following error : "The executable curl Vagrant is trying to run was not found in the %PATH% variable. This is an error. Please verify this software is installed and on the path." A simple solution is to add Cygwin bin folder to path variable or use Git Bash rather than command prompt to run vagrant up prod. For more information, visit this GitHub issue

On Windows 7 the Planet installation might stop if the version of PowerShell is lower than 3, please upgrade the PowerShell by downloading & installing Windows Management Framework 3. Please, read the installation instructions to know which version to download. Your computer will restart and then the installation will resume.

  1. On Ubuntu, you might get this error when you run vagrant up prod:

    Stderr: VBoxManage: error: The virtual machine 'ud381_default_1463617458900_49294' has terminated unexpectedly during startup with exit code 1 (0x1) VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component MachineWrap, interface IMachine

    This is caused when VirtualBox gets a minor version Update. (i.e. 5.0.x -> 5.1.x or 5.1.x -> 5.2.x). There are some old unused modules, which are not compatible with the newer version. They remain installed, which causes the above problem and prevents VirtualBox from starting. A system restart also does not solve the problem.

    To solve it first remove the unused packages using sudo apt-get autoremove. Then reconfigure VirtualBox to install updated modules using sudo /sbin/vboxconfig

  2. If you see the following error:

    The provider 'virtualbox' that was requested to back the machine 'prod' is reporting that it isn't usable on this system. The reason is shown below: VirtualBox is complaining that the installation is incomplete. Please run VBoxManage --version to see the error message which should contain instructions on how to fix this error.

    The problem is the requirement that all kernel modules must be signed by a key trusted by the UEFI system, otherwise loading will fail. Ubuntu does not sign the third party vbox* kernel modules, but rather gives the user the option to disable Secure Boot upon installation of the virtualbox package, so disabling the secure boot on BIOS would solve this problem. If you do not want to disable Secure Boot in some reasons, you can look at this page to make and assign the trusted key(MOK).

  3. If you see "no_db_found" when trying to access http://localhost:3100: At this early stage, the simple solution would be using vagrant destroy prod to delete the current machine, then use vagrant up prod to rebuild it.

  4. If the command vagrant up prod is not working, try to install Virtual Box version 5.1.

  5. On Windows, if you are unable to run the PowerShell command at the beginning of Step 1 and get the error powershell is not recognized as an internal or external command. Try to add the following path variable to your system variables under Advanced Settings: %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\;