aboutsummaryrefslogtreecommitdiffstats
path: root/docs/release/install-guide.rst
blob: a481f60a2029c779857b4bd740ef35bfaf7689bf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
###############################################################################
# Copyright (c) 2017 Koren Lev (Cisco Systems), Yaron Yogev (Cisco Systems)   #
# and others                                                                  #
#                                                                             #
# All rights reserved. This program and the accompanying materials            #
# are made available under the terms of the Apache License, Version 2.0       #
# which accompanies this distribution, and is available at                    #
# http://www.apache.org/licenses/LICENSE-2.0                                  #
###############################################################################
| Calipso.io
| Installation Guide

|image0|

Project “Calipso” tries to illuminate complex virtual networking with
real time operational state visibility for large and highly distributed
Virtual Infrastructure Management (VIM).

We believe that Stability is driven by accurate Visibility.

Calipso provides visible insights using smart discovery and virtual
topological representation in graphs, with monitoring per object in the
graph inventory to reduce error vectors and troubleshooting, maintenance
cycles for VIM operators and administrators.

Table of Contents

Calipso.io Installation Guide 1

1 Pre Requisites 3

1.1 Pre Requisites for Calipso “all in one” application 3

1.2 Pre Requisites for Calipso UI application 3

2 Installation Options 4

2.1 Monolithic App 4

2.2 Micro Services App, single line install 4

2.3 Micro Services App, customized single line install 5

2.4 Micro Services App, customized interactive install 6

3 OPNFV Options 7

3.1 APEX scenarios 7

3.2 Fuel scenarios 7

1. Pre Requisites 
===============

1.1 Pre Requisites for Calipso “all in one” application 
----------------------------------------------------

    Calipso’s main application is written with Python3.5 for Linux
    Servers, tested successfully on Centos 7.3 and Ubuntu 16.04. When
    running using micro-services many of the required software packages
    and libraries are delivered per micro service, but for an “all in
    one” application case there are several dependencies.

    Here is a list of the required software packages, and the official
    supported steps required to install them:

1. Python3.5.x for Linux :
   https://docs.python.org/3.5/using/unix.html#on-linux

2. Pip for Python3 : https://docs.python.org/3/installing/index.html

3. Python3 packages to install using pip3 :

    **sudo pip3 install falcon (>1.1.0)**

    **sudo pip3 install pymongo (>3.4.0)**

    **sudo pip3 install gunicorn (>19.6.0)**

    **sudo pip3 install ldap3 (>2.1.1)**

    **sudo pip3 install setuptools (>34.3.2)**

    **sudo pip3 install python3-dateutil (>2.5.3-2)**

    **sudo pip3 install bcrypt (>3.1.1)**

    **sudo pip3 install bson**

    **sudo pip3 install websocket**

    **sudo pip3 install datetime**

    **sudo pip3 install typing**

    **sudo pip3 install kombu**

    **sudo pip3 install boltons**

    **sudo pip3 install paramiko**

    **sudo pip3 install requests **

    **sudo pip3 install httplib2**

    **sudo pip3 install mysql.connector**

    **sudo pip3 install xmltodict**

    **sudo pip3 install cryptography**

    **sudo pip3 install docker**

4. Git : https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

5. Docker : https://docs.docker.com/engine/installation/

1.2 Pre Requisites for Calipso UI application 
------------------------------------------

    Calipso UI is developed and maintained using Meteor Framework
    (https://www.meteor.com/tutorials). For stability and manageability
    reasons we decided to always build the latest Calipso UI as a Docker
    container pre-parameterized for stable and supported behavior. The
    required steps for installing the Calipso UI with several options
    are listed below.

2. Installation Options
====================

2.1 Monolithic App 
---------------

    For development use, one might require Calipso to be installed as a
    Monolithic Application, to do that all you need is a server
    installed with Calipso pre-requisites and cloning of Calipso’s
    public repository, here are the required steps for this option:

1. Create a user named ‘\ **calipso**\ ’ and give it **sudo** access,
       login as ‘calipso’ user.

2. Create those directories as the ‘calipso’ user : **mkdir -p log &
       mkdir log/calipso**

3. Clone calipso main application from the latest public repository:

    **git clone https://git.opnfv.org/calipso/**

4. Move to the default install directory: **cd calipso**

5. Setup Python3 environment for calipso:

    **export PYTHONPATH=/home/calipso/calipso/app**

6. Follow quick-start guide on how to use calipso modules for monolithic
       scenario, and run each module manually.

2.2 Micro Services App, single line install
---------------------------------------

    For most users, this will be the fastest and more reliable install
    option. We currently have Calipso divided into 7 major containers,
    those are installed using a single installer. The Calipso containers
    are pre-packaged and fully customized per our design needs. Here are
    the required steps for installation using this option:

1. Follow steps 1- 5 per section 2.1 above.

2. Install the following python3 libraries using pip3 : docker, pymongo

3. Although Calipso installer can download all needed containers, if
   they does not exist locally already, we recommend doing a manual
   download of all 7 containers, providing better control and logging:

    **sudo docker login** # use your DockerHub username and password to
    login.

    **sudo docker pull korenlev/calipso:scan** # scan container used to
    scan VIM

    **sudo docker pull korenlev/calipso:listen** # listen container to
    attach to VIM’s BUS.

    **sudo docker pull korenlev/calipso:api** # api container for
    application integration

    **sudo docker pull korenlev/calipso:sensu** # sensu server container
    for monitoring

    **sudo docker pull korenlev/calipso:mongo** # calipso mongo DB
    container

    **sudo docker pull korenlev/calipso:ui** # calipso ui container

    **sudo docker pull korenlev/calipso:ldap** # calipso ldap container

4. Check that all containers were downloaded and registered
   successfully:

    **sudo docker images**

    Expected results (As of Aug 2017):

    **REPOSITORY TAG IMAGE ID CREATED SIZE**

    **korenlev/calipso listen 12086aaedbc3 6 hours ago 1.05GB**

    **korenlev/calipso api 34c4c6c1b03e 6 hours ago 992MB**

    **korenlev/calipso scan 1ee60c4e61d5 6 hours ago 1.1GB**

    **korenlev/calipso sensu a8a17168197a 6 hours ago 1.65GB**

    **korenlev/calipso mongo 17f2d62f4445 22 hours ago 1.31GB**

    **korenlev/calipso ui ab37b366e812 11 days ago 270MB**

    **korenlev/calipso ldap 316bc94b25ad 2 months ago 269MB**

5. Run the calipso installer using single line arguments:

    **python3 calipso/app/install/calipso-installer.py--command
    start-all --copy q**

    This should launch all calipso modules in sequence along with all
    needed configuration files placed in /home/calipso.

2.3 Micro Services App, customized single line install
--------------------------------------------------

    Calipso app includes the following directory in its default
    structure (as of Aug 2017):

    **app/install/db,** this directory holds the initial Database scheme
    and files needed as an initial data for starting Calipso
    application.

    Calipso Database container (calipso-mongo) comes pre-packaged with
    all the necessary initial scheme and files, but in some development
    cases might not be synchronized with the latest ones supported. For
    this reason, the installer has an option to copy files from the
    above directory into the Database after runtime.

    You can run calipso installer using the following single line
    arguments:

1. **--command start-all \| stop-all**

   This will either start (docker run) or stop (docker kill and remove)
   all calipso containers\ **,** a mandatory attribute for a single line
   install option.

2. **--copy q \| c **

   This will either copy all files from app/install/db into mongoDB or
   skip that step, a mandatory attribute for a single line install
   option.

3. **--hostname **

   Allows to enter an IP address or hostname where container will be
   deployed, an optional argument, default IP 172.17.0.1 (docker0
   default) is deployed if not used.

4. **--webport **

   Allows to enter a TCP port to be used for calipso UI on the host, an
   optional argument, default 80 (http default) is deployed if not used.

5. **--dbport **

   Allows to enter a TCP port to be used for mongoDB port on the host,
   an optional argument, default 27017 (mongo default) is deployed if
   not used.

6. **--dbuser **

   Allows to enter a username to be used for mongoDB access on the host,
   an optional argument, default ‘calipso’ (calipso-mongo container’s
   default) is deployed if not used.

7. **--dbpassword **

   Allows to enter a password to be used for mongoDB access on the host,
   an optional argument, default ‘calipso\_default’ (calipso-mongo
   container’s default) is deployed if not used.
   
8. **--apiport **
   Allows to enter a TCP port to be used for the Calipso API (default=8000)
   
9. **--uchiwaport **
   Allows to enter a TCP port to be used for the Sensu UI (default=3000)
   
10. **--rabbitmport **
   Allows to enter a TCP port to be used for the RabbitMQ mgmt (default=15672)
   
11. **--sensuport **
   Allows to enter a TCP port to be used for the Sensu API (default=4567)
   
12.	**--rabbitport **
   Allows to enter a TCP port to be used for the RabbitMQ BUS (default=5671)

2.4 Micro Services App, customized interactive install
--------------------------------------------------

    Calipso’s application containers can be initiated and stopped
    individually for testing purposes, this option is available through
    interactive install, run calipso-installer.py with no argument to
    kickstart the interactive process, allowing the following steps:

1. **Action? (stop, start, or 'q' to quit):**

2. **Container? (all, calipso-mongo, calipso-scan, calipso-listen,
   calipso-ldap, calipso-api, calipso-sensu, calipso-ui or 'q' to
   quit):**

3. **create initial calipso DB ? (copy json files from 'db' folder to
   mongoDB - 'c' to copy, 'q' to skip):**

*Note*: based on the arguments input (or defaults), calipso installer
automatically creates and place 2 configuration files under
/**home/calipso**: **ldap.conf** and **calipso\_mongo\_access.conf**,
those are mandatory configuration files used by calipso containers to
interact with each other!

2.5 OPNFV Options
=============

Although calipso is designed for any VIM and for enterprise use-cases
too, service providers may use additional capability to install calipso
with Apex for OPNFV.

APEX scenarios 
---------------

When using apex to install OPNFV, the Triple-O based OpenStack is
installed automatically and calipso installation can be initiated
automatically after apex completes the VIM installation process for
a certain scenario.

In this case setup_apex_environment.py can be used for creating a new environment automatically into mongoDB and UI of Calipso,
instead of using the calipso UI to do that as typical user would do, then detailed scanning can start immediately, 
the following options are available for setup_apex_environment.py:
     -m [MONGO_CONFIG], --mongo_config [MONGO_CONFIG]
                        name of config file with MongoDB server access details
                        (Default: /local_dir/calipso_mongo_access.conf)
     -d [CONFIG_DIR], --config_dir [CONFIG_DIR]
                        path to directory with config data (Default:
                        /home/calipso/apex_setup_files)
     -i [INSTALL_DB_DIR], --install_db_dir [INSTALL_DB_DIR]
                        path to directory with DB data (Default:
                        /home/calipso/Calipso/app/install/db)
     -a [APEX], --apex [APEX]
                        name of environment to Apex host
     -e [ENV], --env [ENV]
                        name of environment to create(Default: Apex-Euphrates)
     -l [LOGLEVEL], --loglevel [LOGLEVEL]
                        logging level (default: "INFO")
     -f [LOGFILE], --logfile [LOGFILE]
                        log file (default:
                        "/home/calipso/log/apex_environment_fetch.log")
     -g [GIT], --git [GIT]
                        URL to clone Git repository (default:
                        https://git.opnfv.org/calipso)

Fuel scenarios 
---------------

    TBD

.. |image0| image:: media/image1.png
   :width: 6.50000in
   :height: 4.27153in