GettingStartedLinux.html - voltha - Gitiles

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

 <html xmlns="http://www.w3.org/1999/xhtml">

 <head>
 <title>GettingStartedLinux.html</title>

 </head>

 <body>

 <h1>Setting up a clean-slate Linux system for VOLTHA development and execution.</h1>

 <p>Note: These steps have been tested and confirmed on
  * Ubuntu Desktop 16.04.01 LTS release
  * Ubuntu Server 16.04.01 LTS release.</p>

 <p>The purpose of this file is to document the intial packages that need
 to be installed on a Linux system so that you can execute the basic
 installation procedure documented in BUILD.md</p>

 <p>The following steps can be executed in order and have been tested (and
 retested) on various Linux VMs. If you find any issues with the steps
 below, please update this file accordingly.</p>

 <p>Regarding Linux VMs, I found that I needed to allocate at lest 6GB of
 RAM to my VM, otherwise I would run out of memory while fetching the
 docker images.</p>

 <p>October, 2016 - Minimum Linux VM requirements</p>

 <p>| Cores | RAM | Disk |
 |-------|-----|------|
 | 2     | 6GB | 20GB |</p>

 <h3>Update</h3>

 <p>To begin with, please make sure you machine is up to date with the
 latest packages and that you have python-pip installed.</p>

 <p><code>
 $ sudo apt update
 $ sudo apt upgrade --yes
 $ sudo apt install python-pip
 $ sudo pip install --upgrade pip
 </code></p>

 <h3>Base Packages</h3>

 <p>Next, install the following base packages that will be needed to
 successfully install and compile the virtualenv.</p>

 <p><code>
 $ sudo apt install git --yes
 $ sudo apt install make --yes
 $ sudo apt install virtualenv --yes
 $ sudo apt install curl --yes
 $ sudo apt install jq --yes
 $ sudo apt install libssl-dev --yes
 $ sudo apt install libffi-dev --yes
 $ sudo apt install libpcap-dev --yes
 </code></p>

 <p>Python 2.x is needed in the native environment for (at least) the repo
 tool (installed below). </p>

 <p>And, Python-dev is needed when the pip packages are installed while
 setting up the virtualenv.</p>

 <p>To install python 2.X use the following command.</p>

 <p><code>
 $ sudo apt install python --yes
 $ sudo apt install python-dev --yes
 </code></p>

 <h3>Virtual Box</h3>

 <p>There are a couple of different ways to use Vagrant, the following
 steps assume that you install VirtualBox.</p>

 <p><code>
 $ sudo sh -c "/bin/echo 'deb http://download.virtualbox.org/virtualbox/debian xenial contrib' &gt;&gt; /etc/apt/sources.list"
 </code></p>

 <p><code>
 $ wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
 $ sudo apt-key add oracle_vbox_2016.asc
 </code></p>

 <p><code>
 $ wget https://www.virtualbox.org/download/oracle_vbox.asc
 $ sudo apt-key add oracle_vbox.asc
 </code></p>

 <p>VirtualBox-5.1 is the latest release of VirtualBox, yet it is not
 compatible with the Ubuntu 16.04 default version of <em>vagrant</em>.  The best
 release of VirtualBox to install is 5.0. </p>

 <p>Here is the note from vagrant...</p>

 <pre>
 The provider 'virtualbox' that was requested to back the machine
 'voltha' is reporting that it isn't usable on this system. The
 reason is shown below:

 Vagrant has detected that you have a version of VirtualBox installed
 that is not supported by this version of Vagrant. Please install one of
 the supported versions listed below to use Vagrant:

 4.0, 4.1, 4.2, 4.3, 5.0

 A Vagrant update may also be available that adds support for the version
 you specified. Please check www.vagrantup.com/downloads.html to download
 the latest version.
 </pre>

 <p><code>
 $ sudo apt update
 sudo apt install virtualbox-5.0 --yes
 sudo apt install vagrant
 </code></p>

 <h3>Google repo tool</h3>

 <p>Install the Google repo tool for working with the VOLTHA repository.
 Installing from Google APIs (googleapis below) seems to be a step that
 is blocked by many corporate firewalls.  An alternative is to install
 repo from the apt packages.</p>

 <p><code>
 $ sudo apt install repo --yes
 </code></p>

 <p>Note: The Ubuntu repo package, when executed, may complain about being
 out of date.  Follow the upgrade commands that repo puts to the
 standard out.</p>

 <p>Some older linux distributions do not have repo available.  If you
 cannot apt install repo, then follow the commands below to fetch repo
 from the Google site.  Skip this collection of steps if you have
 installed repo with apt.  </p>

 <p><code>
 $ mkdir ~/bin
 $ PATH=~/bin:$PATH
 $ curl https://storage.googleapis.com/git-repo-downloads/repo &gt; ~/bin/repo
 $ chmod a+x ~/bin/repo
 </code></p>

 <h3>GIT environment</h3>

 <p>Repo requires that at least your git config is setup.  Set it up for
 your user.name and user.email.</p>

 <p><code>
 $ git config --global user.email "&lt;email address&gt;"
 $ git config --global user.name "Firstname Lastname"
 </code></p>

 <h3>Getting the VOLTHA code</h3>

 <p><code>
 $ mkdir cord
 $ cd cord
 $ repo init -u https://gerrit.opencord.org/manifest
 $ repo sync
 </code></p>

 <p><code>
 $ cd incubator/voltha
 voltha$ . ./env.sh
 </code></p>

 <p>The last step above the sources the virtualenv enviroment should
 pass.  If it does not and exits because of an error, see the commands
 below. </p>

 <h3>Virtualenv ERROR Handling</h3>

 <p>When you start with a clean Linux system, the first time virtualenv is
 setup it installs a number of pip packages.  If the base packages on
 the machine are not present for the pip packages to be installed
 correctly, then the virtualenv may be in a half-configured state.</p>

 <p>If you find yourself in this state, the error should be addressed, the
 virtualenv directory should be deleted, and the environment should be
 sourced again.</p>

 <p><code>
 voltha$ rm -rf venv-linux
 &lt; Fix virtualenv environment &gt;
 voltha$ . ./env.sh
 </code></p>

 <h3>Verify working VOLTHA</h3>

 <p>Thes commands are meant to be identical to the commands documented in
 BUILD.md.  At this point you are finished with the basic Linux
 configuration and should be able to start working with VOLTHA. </p>

 <p><code>
 cd incubator/voltha
 vagrant up  # when you do this for the first time, this will take considerable time
 vagrant ssh # the rest to be executed inside the vagrant VM
 cd /voltha
 . env.sh
 make fetch
 make
 </code></p>

 <h3>Advanced Commands</h3>

 <p>If you are running the former pyofagent, then you will need the
 following packages installed in your <strong>native</strong> environment.</p>

 <p><code>
 $ sudo apt install mininet --yes
 $ sudo apt install netifaces --yes
 </code></p>

 </body>
 </html>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

	<html xmlns="http://www.w3.org/1999/xhtml">

	<head>
	<title>GettingStartedLinux.html</title>

	</head>

	<body>

	<h1>Setting up a clean-slate Linux system for VOLTHA development and execution.</h1>

	<p>Note: These steps have been tested and confirmed on
	* Ubuntu Desktop 16.04.01 LTS release
	* Ubuntu Server 16.04.01 LTS release.</p>

	<p>The purpose of this file is to document the intial packages that need
	to be installed on a Linux system so that you can execute the basic
	installation procedure documented in BUILD.md</p>

	<p>The following steps can be executed in order and have been tested (and
	retested) on various Linux VMs. If you find any issues with the steps
	below, please update this file accordingly.</p>

	<p>Regarding Linux VMs, I found that I needed to allocate at lest 6GB of
	RAM to my VM, otherwise I would run out of memory while fetching the
	docker images.</p>

	<p>October, 2016 - Minimum Linux VM requirements</p>

	<p>\| Cores \| RAM \| Disk \|
	\|-------\|-----\|------\|
	\| 2 \| 6GB \| 20GB \|</p>

	<h3>Update</h3>

	<p>To begin with, please make sure you machine is up to date with the
	latest packages and that you have python-pip installed.</p>

	<p><code>
	$ sudo apt update
	$ sudo apt upgrade --yes
	$ sudo apt install python-pip
	$ sudo pip install --upgrade pip
	</code></p>

	<h3>Base Packages</h3>

	<p>Next, install the following base packages that will be needed to
	successfully install and compile the virtualenv.</p>

	<p><code>
	$ sudo apt install git --yes
	$ sudo apt install make --yes
	$ sudo apt install virtualenv --yes
	$ sudo apt install curl --yes
	$ sudo apt install jq --yes
	$ sudo apt install libssl-dev --yes
	$ sudo apt install libffi-dev --yes
	$ sudo apt install libpcap-dev --yes
	</code></p>

	<p>Python 2.x is needed in the native environment for (at least) the repo
	tool (installed below). </p>

	<p>And, Python-dev is needed when the pip packages are installed while
	setting up the virtualenv.</p>

	<p>To install python 2.X use the following command.</p>

	<p><code>
	$ sudo apt install python --yes
	$ sudo apt install python-dev --yes
	</code></p>

	<h3>Virtual Box</h3>

	<p>There are a couple of different ways to use Vagrant, the following
	steps assume that you install VirtualBox.</p>

	<p><code>
	$ sudo sh -c "/bin/echo 'deb http://download.virtualbox.org/virtualbox/debian xenial contrib' >> /etc/apt/sources.list"
	</code></p>

	<p><code>
	$ wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
	$ sudo apt-key add oracle_vbox_2016.asc
	</code></p>

	<p><code>
	$ wget https://www.virtualbox.org/download/oracle_vbox.asc
	$ sudo apt-key add oracle_vbox.asc
	</code></p>

	<p>VirtualBox-5.1 is the latest release of VirtualBox, yet it is not
	compatible with the Ubuntu 16.04 default version of <em>vagrant</em>. The best
	release of VirtualBox to install is 5.0. </p>

	<p>Here is the note from vagrant...</p>

	<pre>
	The provider 'virtualbox' that was requested to back the machine
	'voltha' is reporting that it isn't usable on this system. The
	reason is shown below:

	Vagrant has detected that you have a version of VirtualBox installed
	that is not supported by this version of Vagrant. Please install one of
	the supported versions listed below to use Vagrant:

	4.0, 4.1, 4.2, 4.3, 5.0

	A Vagrant update may also be available that adds support for the version
	you specified. Please check www.vagrantup.com/downloads.html to download
	the latest version.
	</pre>

	<p><code>
	$ sudo apt update
	sudo apt install virtualbox-5.0 --yes
	sudo apt install vagrant
	</code></p>

	<h3>Google repo tool</h3>

	<p>Install the Google repo tool for working with the VOLTHA repository.
	Installing from Google APIs (googleapis below) seems to be a step that
	is blocked by many corporate firewalls. An alternative is to install
	repo from the apt packages.</p>

	<p><code>
	$ sudo apt install repo --yes
	</code></p>

	<p>Note: The Ubuntu repo package, when executed, may complain about being
	out of date. Follow the upgrade commands that repo puts to the
	standard out.</p>

	<p>Some older linux distributions do not have repo available. If you
	cannot apt install repo, then follow the commands below to fetch repo
	from the Google site. Skip this collection of steps if you have
	installed repo with apt. </p>

	<p><code>
	$ mkdir ~/bin
	$ PATH=~/bin:$PATH
	$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
	$ chmod a+x ~/bin/repo
	</code></p>

	<h3>GIT environment</h3>

	<p>Repo requires that at least your git config is setup. Set it up for
	your user.name and user.email.</p>

	<p><code>
	$ git config --global user.email "<email address>"
	$ git config --global user.name "Firstname Lastname"
	</code></p>

	<h3>Getting the VOLTHA code</h3>

	<p><code>
	$ mkdir cord
	$ cd cord
	$ repo init -u https://gerrit.opencord.org/manifest
	$ repo sync
	</code></p>

	<p><code>
	$ cd incubator/voltha
	voltha$ . ./env.sh
	</code></p>

	<p>The last step above the sources the virtualenv enviroment should
	pass. If it does not and exits because of an error, see the commands
	below. </p>

	<h3>Virtualenv ERROR Handling</h3>

	<p>When you start with a clean Linux system, the first time virtualenv is
	setup it installs a number of pip packages. If the base packages on
	the machine are not present for the pip packages to be installed
	correctly, then the virtualenv may be in a half-configured state.</p>

	<p>If you find yourself in this state, the error should be addressed, the
	virtualenv directory should be deleted, and the environment should be
	sourced again.</p>

	<p><code>
	voltha$ rm -rf venv-linux
	< Fix virtualenv environment >
	voltha$ . ./env.sh
	</code></p>

	<h3>Verify working VOLTHA</h3>

	<p>Thes commands are meant to be identical to the commands documented in
	BUILD.md. At this point you are finished with the basic Linux
	configuration and should be able to start working with VOLTHA. </p>

	<p><code>
	cd incubator/voltha
	vagrant up # when you do this for the first time, this will take considerable time
	vagrant ssh # the rest to be executed inside the vagrant VM
	cd /voltha
	. env.sh
	make fetch
	make
	</code></p>

	<h3>Advanced Commands</h3>

	<p>If you are running the former pyofagent, then you will need the
	following packages installed in your <strong>native</strong> environment.</p>

	<p><code>
	$ sudo apt install mininet --yes
	$ sudo apt install netifaces --yes
	</code></p>

	</body>
	</html>