docs/APPC Deployment Guidelines/APPC Building Guidelines.rst

   1 .. ============LICENSE_START==========================================
   2 .. ===================================================================
   3 .. Copyright © 2020 AT&T Intellectual Property. All rights reserved.
   4 .. ===================================================================
   5 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.  (the "License");
   6 .. you may not use this documentation except in compliance with the License.
   7 .. You may obtain a copy of the License at
   8 ..
   9 ..  https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 .. Unless required by applicable law or agreed to in writing, software
  12 .. distributed under the License is distributed on an "AS IS" BASIS,
  13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 .. See the License for the specific language governing permissions and
  15 .. limitations under the License.
  16 .. ============LICENSE_END============================================
  17
  18 =============
  19 Building APPC
  20 =============
  21
  22 Introduction
  23 ============
  24
  25 Building of the Appc containers requires a several steps to be performed. Appc is comprised of several repositories
  26 which must be built in order, since they depend on each other.
  27
  28 Here is a quick overview of the appc repositories:
  29
  30 - **appc/parent:** The maven parent pom files for the rest of the appc projects are kept here. This repository needs to
  31   be built first, since these parent pom files are referenced by other appc repositories.
  32
  33 - **appc:** The main Java code for appc is kept here. This repository should be built after building the appc/parent
  34   repository.
  35
  36 - **appc/cdt:** This repository contains two parts. The "CdtProxyService" directory contains Java code for the proxy
  37   service which recieves requests from the CDT application. The rest of the code in the appc/cdt project is Angular/JS
  38   code for the APPC CDT front end gui. Both parts will be built as part of a maven build on the app/cdt repository.
  39
  40 - **appc/deployment:** This repository contains the scripts to build the APPC docker containers. This repository should
  41   be built last, since it pulls artifacts from the appc and appc/cdt builds.
  42
  43 Building Prerequisites
  44 ======================
  45
  46 APPC is built using Maven. You will need to make sure that Maven and a Java compiler are installed. Currently, APPC is
  47 building on Java 1.8.
  48
  49 In order to build the appc/deployment project and the Docker images, you must have a Docker host. Docker can be running
  50 on the same system you use for Maven builds and development work. You can also run Docker on a separate host, if you
  51 choose to do so. If your Docker host is on a separate system, you need to set the DOCKER_HOST environment variable
  52 before running the appc/deployment Maven build.
  53
  54 .. code:: bash
  55
  56   #DOCKER_HOST should only need to be set if your Docker host is not local
  57   export DOCKER_HOST=tcp://<ip address of your Docker host>:4243
  58
  59 Cloning Code Repositories
  60 =========================
  61
  62 The first step in building APPC is to clone the four appc repositories (listed above) using git. (appc/parent, appc,
  63 appc/cdt, appc/deployment)
  64
  65 Building APPC Parent
  66 ====================
  67
  68 First we'll build appc parent. From the appc/parent directory, run a maven clean install:
  69
  70 .. code:: bash
  71
  72   mvn clean install
  73
  74 Building main APPC
  75 ==================
  76
  77 Before building the main appc repository, you need to make sure that references to the appc parent files have the same
  78 version as the pom files in the parent repository that you just built. You can search for the text
  79 "org.onap.appc.parent" in all of the pom.xml files in the appc repository. Check if the version matches the version of
  80 app/parent that you just built. A find/replace on the <version> tag can be performed, if it needs to be changed.
  81
  82 The appc repository can then be built with a maven clean install.
  83
  84 Building APPC CDT
  85 =================
  86
  87 The appc/cdt repository should just be built with a maven clean install. This should build both the Java code in the
  88 CdtProxyService, as well as the Angular code.
  89
  90 Building APPC Deployment (building the Docker images)
  91 =====================================================
  92
  93 The appc/deployment repository will perform several build steps in order to build the APPC Docker images.
  94
  95 appc-image Docker Build Preparation
  96 -----------------------------------
  97
  98 The appc-image build occurs first. The build begins by downloading the APPC artifacts that were created by the main appc
  99 maven build. You need to make sure the version of APPC that will be downloaded matches the version of APPC that you
 100 built in the previous steps, see the "Setting APPC Versions" section below.
 101
 102 The appc-image Docker image is built on top of the ccsdk-odlsli-alpine-image. The version of the ccsdk image that will
 103 be used is defined in the installation/appc/src/main/docker/Dockerfile file. This image will need to be downloaded
 104 before the Docker build is performed:
 105
 106 .. code:: bash
 107
 108   docker pull nexus3.onap.org:10001/onap/ccsdk-odlsli-alpine-image:<image version>
 109
 110 Using the "docker tag" command, you should then tag the image you downloaded so that the image name exactly matches what
 111 is shown in the Dockerfile.
 112 (Please see the "APPC Deployment Guidelines" page for more information on setting up Docker and downloading images)
 113
 114
 115 appc-cdt-image Docker Build Preparation
 116 ---------------------------------------
 117
 118 The appc-cdt-image build will download the cdt Angular code zip file that was created during your appc/cdt build earlier.
 119 Similar to the appc-image build, you will have to make sure that the version of this zip that is being downloaded
 120 matches the version that you built earlier, see the "Setting APPC Versions" section below for how to do this.
 121
 122 Setting APPC Versions
 123 ---------------------
 124
 125 The versions of APPC that will be downloaded by the Docker build are set in the properties section of the
 126 installation/appc/pom.xml file:
 127
 128 - **<appc.snapshot.version>:** This property sets the version of APPC to download to the Docker image. This version will
 129   be used in any build where the appc/deployment pom versions are set to any "-SNAPSHOT" version (this will usually be
 130   the case for local builds).
 131 - **<appc.release.version>:** This property sets the version of APPC to download to the Docker image. This version will
 132   be used in any build where the appc/deployment pom versions do NOT contain "-SNAPSHOT" (this will usually only be used
 133   for the staging jobs on Jenkins).
 134 - **<appc.cdt.version>:** This property sets the version of the APPC CDT proxy service that will be downloaded to the
 135   Docker image. This property should be set to the version of the appc/cdt repository that you built earlier. Or, if you
 136   didn't modify the CDT proxy code, you can leave this as it is, and a version will be downloaded from ONAP Nexus.
 137
 138 The version of the CDT code that will be downloaded by the Docker build is set in the properties section of the
 139 cdt/pom.xml file:
 140
 141 - **<appc.snapshot.version>:** This property sets the version of APPC CDT to download to the Docker image. This version
 142   will be used in any build where the appc/deployment pom versions are set to any "-SNAPSHOT" version (this will usually
 143   be the case for local builds).
 144 - **<appc.release.version>:** This property sets the version of APPC CDT to download to the Docker image. This version
 145   will be used in any build where the appc/deployment pom versions do NOT contain "-SNAPSHOT" (this will usually only be
 146   used for the staging jobs on Jenkins).
 147
 148 Building the Docker containers
 149 ------------------------------
 150
 151 A maven clean install with the profile "docker" is used to start the appc/deployment and Docker build:
 152
 153 .. code:: bash
 154
 155   mvn clean install -P docker
 156
 157 **NOTE:** In some cases, you may see the appc/deployment build downloading APPC artifacts from Nexus, instead of using
 158 the artifacts that you built locally from the appc and appc/cdt builds. This can happen if two conditions are met:
 159
 160 1. Your appc and appc/cdt local versions are set to the same version as they are in Gerrit.
 161 2. ONAP Jenkins has run a merge job more recently than you performed your local build.
 162
 163 In this case, your appc/deployment build will see that the snapshot version in Nexus is newer than the version which
 164 exists locally, and it will download that version instead of using the local one.
 165
 166
 167