Gitiles
Code Review Sign In
gerrit.opencord.org / voltha / ab39c0ea39bf5ff61b51b699260ca0008e5b2614 / . / GettingStartedLinux.html
blob: fdce7b8abf597949dcb600e7dc2c3a808eca8e75 [file] [log] [blame]
Nathan Knuth498573e2017-01-18 08:07:00 -0600[diff] [blame]1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6
7<head>
8<title>GettingStartedLinux.html</title>
9
10</head>
11
12<body>
13
14<h1>Setting up a clean-slate Linux system for VOLTHA development and execution.</h1>
15
16<p>Note: These steps have been tested and confirmed on
17 * Ubuntu Desktop 16.04.01 LTS release
18 * Ubuntu Server 16.04.01 LTS release.</p>
19
20<p>The purpose of this file is to document the intial packages that need
21to be installed on a Linux system so that you can execute the basic
22installation procedure documented in BUILD.md</p>
23
24<p>The following steps can be executed in order and have been tested (and
25retested) on various Linux VMs. If you find any issues with the steps
26below, please update this file accordingly.</p>
27
28<p>Regarding Linux VMs, I found that I needed to allocate at lest 6GB of
29RAM to my VM, otherwise I would run out of memory while fetching the
30docker images.</p>
31
32<p>October, 2016 - Minimum Linux VM requirements</p>
33
34<p>| Cores | RAM | Disk |
35|-------|-----|------|
36| 2 | 6GB | 20GB |</p>
37
38<h3>Update</h3>
39
40<p>To begin with, please make sure you machine is up to date with the
41latest packages and that you have python-pip installed.</p>
42
43<p><code>
44$ sudo apt update
45$ sudo apt upgrade --yes
46$ sudo apt install python-pip
47$ sudo pip install --upgrade pip
48</code></p>
49
50<h3>Base Packages</h3>
51
52<p>Next, install the following base packages that will be needed to
53successfully install and compile the virtualenv.</p>
54
55<p><code>
56$ sudo apt install git --yes
57$ sudo apt install make --yes
58$ sudo apt install virtualenv --yes
59$ sudo apt install curl --yes
60$ sudo apt install jq --yes
61$ sudo apt install libssl-dev --yes
62$ sudo apt install libffi-dev --yes
63$ sudo apt install libpcap-dev --yes
64</code></p>
65
66<p>Python 2.x is needed in the native environment for (at least) the repo
67tool (installed below). </p>
68
69<p>And, Python-dev is needed when the pip packages are installed while
70setting up the virtualenv.</p>
71
72<p>To install python 2.X use the following command.</p>
73
74<p><code>
75$ sudo apt install python --yes
76$ sudo apt install python-dev --yes
77</code></p>
78
79<h3>Virtual Box</h3>
80
81<p>There are a couple of different ways to use Vagrant, the following
82steps assume that you install VirtualBox.</p>
83
84<p><code>
85$ sudo sh -c "/bin/echo 'deb http://download.virtualbox.org/virtualbox/debian xenial contrib' &gt;&gt; /etc/apt/sources.list"
86</code></p>
87
88<p><code>
89$ wget https://www.virtualbox.org/download/oracle_vbox_2016.asc
90$ sudo apt-key add oracle_vbox_2016.asc
91</code></p>
92
93<p><code>
94$ wget https://www.virtualbox.org/download/oracle_vbox.asc
95$ sudo apt-key add oracle_vbox.asc
96</code></p>
97
98<p>VirtualBox-5.1 is the latest release of VirtualBox, yet it is not
99compatible with the Ubuntu 16.04 default version of <em>vagrant</em>. The best
100release of VirtualBox to install is 5.0. </p>
101
102<p>Here is the note from vagrant...</p>
103
104<pre>
105The provider 'virtualbox' that was requested to back the machine
106'voltha' is reporting that it isn't usable on this system. The
107reason is shown below:
108
109Vagrant has detected that you have a version of VirtualBox installed
110that is not supported by this version of Vagrant. Please install one of
111the supported versions listed below to use Vagrant:
112
1134.0, 4.1, 4.2, 4.3, 5.0
114
115A Vagrant update may also be available that adds support for the version
116you specified. Please check www.vagrantup.com/downloads.html to download
117the latest version.
118</pre>
119
120<p><code>
121$ sudo apt update
122sudo apt install virtualbox-5.0 --yes
123sudo apt install vagrant
124</code></p>
125
126<h3>Google repo tool</h3>
127
128<p>Install the Google repo tool for working with the VOLTHA repository.
129Installing from Google APIs (googleapis below) seems to be a step that
130is blocked by many corporate firewalls. An alternative is to install
131repo from the apt packages.</p>
132
133<p><code>
134$ sudo apt install repo --yes
135</code></p>
136
137<p>Note: The Ubuntu repo package, when executed, may complain about being
138out of date. Follow the upgrade commands that repo puts to the
139standard out.</p>
140
141<p>Some older linux distributions do not have repo available. If you
142cannot apt install repo, then follow the commands below to fetch repo
143from the Google site. Skip this collection of steps if you have
144installed repo with apt. </p>
145
146<p><code>
147$ mkdir ~/bin
148$ PATH=~/bin:$PATH
149$ curl https://storage.googleapis.com/git-repo-downloads/repo &gt; ~/bin/repo
150$ chmod a+x ~/bin/repo
151</code></p>
152
153<h3>GIT environment</h3>
154
155<p>Repo requires that at least your git config is setup. Set it up for
156your user.name and user.email.</p>
157
158<p><code>
159$ git config --global user.email "&lt;email address&gt;"
160$ git config --global user.name "Firstname Lastname"
161</code></p>
162
163<h3>Getting the VOLTHA code</h3>
164
165<p><code>
166$ mkdir cord
167$ cd cord
168$ repo init -u https://gerrit.opencord.org/manifest
169$ repo sync
170</code></p>
171
172<p><code>
173$ cd incubator/voltha
174voltha$ . ./env.sh
175</code></p>
176
177<p>The last step above the sources the virtualenv enviroment should
178pass. If it does not and exits because of an error, see the commands
179below. </p>
180
181<h3>Virtualenv ERROR Handling</h3>
182
183<p>When you start with a clean Linux system, the first time virtualenv is
184setup it installs a number of pip packages. If the base packages on
185the machine are not present for the pip packages to be installed
186correctly, then the virtualenv may be in a half-configured state.</p>
187
188<p>If you find yourself in this state, the error should be addressed, the
189virtualenv directory should be deleted, and the environment should be
190sourced again.</p>
191
192<p><code>
193voltha$ rm -rf venv-linux
194&lt; Fix virtualenv environment &gt;
195voltha$ . ./env.sh
196</code></p>
197
198<h3>Verify working VOLTHA</h3>
199
200<p>Thes commands are meant to be identical to the commands documented in
201BUILD.md. At this point you are finished with the basic Linux
202configuration and should be able to start working with VOLTHA. </p>
203
204<p><code>
205cd incubator/voltha
206vagrant up # when you do this for the first time, this will take considerable time
207vagrant ssh # the rest to be executed inside the vagrant VM
208cd /voltha
209. env.sh
210make fetch
211make
212</code></p>
213
214<h3>Advanced Commands</h3>
215
216<p>If you are running the former pyofagent, then you will need the
217following packages installed in your <strong>native</strong> environment.</p>
218
219<p><code>
220$ sudo apt install mininet --yes
221$ sudo apt install netifaces --yes
222</code></p>
223
224</body>
225</html>