bootstrap/vagrant-onap/doc/source/features/example_usage.rst

   1 =================================================
   2 Example usage to bring up a developer environment
   3 =================================================
   4
   5 In the example, we will bring up a single ONAP component using the Vagrant ONAP
   6 tool.
   7
   8 There are multiple scenarios in which this tool can be made use of by a
   9 developer, they usually fall in the following use cases.
  10
  11 Use case 1: Use Vagrant ONAP to just clone project related source code
  12 ----------------------------------------------------------------------
  13
  14 In this use case, the developer needs just the source code of the project to work on.
  15
  16 Since the Vagrant ONAP project supports building docker containers and compiling
  17 source files, we need to first edit the settings.yaml file to add key value pairs
  18 indicating we need to only clone repo and not build docker image or compile then.
  19 By default, Vagrant ONAP clones repo, but to not run the build process and cloning
  20 docker images, the following are required to be added in the settings file.
  21
  22 .. code-block:: console
  23
  24     skip_get_images: "True"
  25
  26 .. end
  27
  28 The reason this is done is because as mentioned in the
  29 `configure execution docs. <https://git.onap.org/integration/tree/bootstrap/vagrant-onap/doc/source/features/configure_execution.rst>`,
  30 the default values taken are:
  31
  32 .. code-block:: console
  33
  34     'build_image'         => 'True',
  35     'clone_repo'          => 'True',
  36     'compile_repo'        => 'False',
  37     'enable_oparent'      => 'True',
  38     'skip_get_images'     => 'False',
  39     'skip_install'        => 'True'
  40
  41 .. end
  42
  43 We override them and skip_get_images is given precedence over build_image.
  44
  45 Use case 2: Use Vagrant ONAP to clone project related source code and clone Docker Images
  46 -----------------------------------------------------------------------------------------
  47
  48 In this use case, the developer needs to clone docker images of the project to work on.
  49
  50 For this case, we will edit the settings.yaml file to add key value pairs indicating we
  51 need to clone repo and clone docker image from Nexus.
  52
  53 .. code-block:: console
  54
  55     build_images: "False"
  56     compile_repo: "True"
  57     skip_get_images: "False"
  58     skip_install: "True"
  59
  60 .. end
  61
  62 Use case 3: Use Vagrant ONAP to clone project related source code and build Docker Images locally
  63 -------------------------------------------------------------------------------------------------
  64
  65 In this use case, the developer needs to build docker images of the project to work on.
  66
  67 For this case, we will edit the settings.yaml file to add key value pairs indicating we need to
  68 clone repo and build docker image locally and not fetch them from Nexus.
  69
  70 .. code-block:: console
  71
  72     build_images: "True"
  73     compile_repo: "True"
  74     skip_get_images: "False"
  75     skip_install: "True"
  76
  77 .. end
  78
  79 Use case 4: Use Vagrant ONAP to clone project related source code and build Docker Images and start services
  80 ------------------------------------------------------------------------------------------------------------
  81
  82 In this use case, the developer needs to build docker images of the project he or
  83 she wanted to work on and start the services running inside them.
  84
  85 For this case, we will edit the settings.yaml file to add key value pairs indicating
  86 we need to clone repo, compile repo, build docker image and run the image.
  87
  88 .. code-block:: console
  89
  90     build_images: "True"
  91     compile_repo: "True"
  92     skip_get_images: "False"
  93     skip_install: "False"
  94
  95 .. end
  96
  97 Once the required changes to the settings file is added, we can use the run.sh
  98 script in tools directory to setup the development environment.
  99
 100 Example steps for setting up a development environment for VFC project.
 101 -----------------------------------------------------------------------
 102
 103 In this example we will be using vagrant ONAP to get all the source code of VFC
 104 project and the developer can point the IDE to the cloned repo in the ./opt directory
 105 and start the development process.
 106
 107 .. code-block:: console
 108
 109    $ ./tools/run.sh vfc
 110
 111 .. end
 112
 113 At the end of the setup process, all the VFC related source code will be present
 114 in the vagrant-onap/opt/ directory. The developer can point an IDE to this directory
 115 and start contributing. When the changes are done, the developer can SSH into the VM
 116 running VFC and tests can be executed by running Maven for Java and Tox for Python
 117 from the ~/opt/vfc directory.
 118
 119 .. code-block:: console
 120
 121    $ vagrant ssh vfc
 122    $ cd ~/opt/vfc/<vfc-subrepo>
 123    $ tox -e py27
 124
 125 .. end
 126
 127 This way the tool helps the developer to clone repos of a particular project,
 128 without having to manually search for repos and setup an environment.
 129
 130 Also, if something gets messed up in the VM, the developer can tear down the VM
 131 and spin a fresh one without having to lose the changes made to the source code since
 132 the ./opt files are in sync from the host to the VM.
 133
 134 .. code-block:: console
 135
 136    $ vagrant destroy vfc
 137
 138 .. end
 139
 140 Testing
 141 -------
 142
 143 Use the run.sh script to test if the provisioning scripts run without errors.
 144
 145 And example test to check the number of covered repositories with this tool.
 146
 147 .. code-block:: console
 148
 149    $ ./tools/run.sh testing -y -c coverity_repos -s functions
 150
 151 .. end