1 .. ============LICENSE_START==========================================
2 .. ===================================================================
3 .. Copyright © 2017 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
9 .. https://creativecommons.org/licenses/by/4.0/
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 .. ECOMP is a trademark and service mark of AT&T Intellectual Property.
19 ======================================
20 APPC Testing of a Local ONAP Component
21 ======================================
24 *NOTE: Tested on APPC ONAP Component only, on a single Ubuntu 16.04 LTS
28 ONAP <https://wiki.onap.org/display/DW/Developing+ONAP>`__
34 - A Gerrit Account – to create a Gerrit account, please create one
35 here: https://identity.linuxfoundation.org
39 - An Ubuntu 16.04 LTS Desktop VM (14.04 LTS should work as well)
42 - 40 GB of hard disk drive
43 - 4 vCPUs should suffice
45 - Software Download Requirements:
47 - Eclipse IDE for Java EE Developers (latest stable release is neon
49 http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/neon3
50 - Nexus OSS 2 (to upload ONAP Component’s Maven Artifacts locally):
51 https://www.sonatype.com/download-oss-sonatype - grab the
53 - Nexus OSS 3 (to upload ONAP Component’s Docker Image locally):
54 https://www.sonatype.com/download-oss-sonatype - grab the
56 - Apache Maven (latest stable version is 3.3.9):
57 https://maven.apache.org/download.cgi - grab the binary tar.gz
61 Installation procedure
62 ======================
67 - First, download all of the Ubuntu apt packages needed:
71 sudo apt-get -y install openjdk-8-jdk maven git-review
76 - Set up your git information:
80 git config --global user.email your_LF_account@email
81 git config --global --add gitreview.username your_LF_user_name
83 - NOTE: For people using VPN/Proxy, you might have proxy problem
84 while connecting to LF website. To avoid the problem, you should
85 add the proxy setting in git config, using the following command:
89 git config --global https.proxy https://<proxy_username>:<proxy_password>@<proxy_url>
90 git config --global http.proxy http://<proxy_username>:<proxy_password>@<proxy_url>
92 - Generate an HTTP Password in order to clone the necessary git repos:
94 - Go to https://gerrit.onap.org
95 - As highlighted below, go to Settings --> HTTP Password -->
100 - On a clean folder on your Desktop (or your preferred path), create a
101 folder and clone the ONAP APPC Git Repositories that we will test
102 with (NOTE: Use the previously generated HTTP Password to
107 git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc
108 git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc/deployment
110 Docker Engine Installation
111 --------------------------
114 link <https://docs.docker.com/engine/installation/linux/ubuntu/>`__
115 to set up the Docker Engine on your local machine (you will need this
116 to store the Docker Images that will be uploaded in the local Nexus
119 Setting up Nexus 2 and 3 OSS Repositories
120 -----------------------------------------
122 - Install & run Nexus OSS 2 without sudo rights as a non-root user
123 (detailed and clear instructions on how to do install it are
124 `here <https://books.sonatype.com/nexus-book/reference/installing.html>`__
126 `here <https://books.sonatype.com/nexus-book/reference/running.html>`__)
128 - Default Nexus 2 OSS Local Webpage: http://localhost:8081/nexus
129 - Check nexus logs: $NEXUS\_HOME/logs/wrapper.log
130 - Default credentials: username is deployment, password is
133 - Install & run Nexus OSS 3 without sudo rights as a non-root user
134 (detailed and clear instructions on how to do are
135 `here <https://books.sonatype.com/nexus-book/reference3/install.html#installation-archive>`__)
137 - IMPORTANT: Since both Nexus 2 and Nexus 3’s web sites run on port
138 8081, the Nexus 3 OSS needs to modify its configuration to start
139 up as a process in another port so as to avoid a conflict.
140 Therefore, follow the instructions here to start up Nexus 3 OSS on
141 another port (in the link, $data-dir usually refers to the
142 sonatype-work folder that the nexus tar file generates after being
144 - Nexus 3 OSS Local Webpage (assuming the port was changed as
145 explained above): http://localhost:9081
146 - Check nexus3 bootup logs: $data-dir/nexus3/log/nexus.log
147 - Check nexus3 logs: $data-dir/nexus3/log/jvm.log
148 - Default credentials: username is admin, default password is
151 - Create a Docker Registry Repository on Nexus 3 OSS Webpage
153 - In order to be able to deploy docker images to Nexus 3 OSS
154 Repository, you need to create a Docker Registry where you will
155 upload these docker images to.
156 - Go to http://localhost:9081 to access the Nexus 3 OSS Webpage, log
157 on, click on settings icon, and then click on “Repositories” which
158 will give you the option to “Create Repository” as shown below:
162 - On the next window, choose the “Docker (Hosted)” option
164 - NOTE: you can choose the “Docker (Proxy)” option if you have a
165 docker registry outside of your local Nexus 3 OSS that you want
166 to externally connect to, such as the public docker.io registry
169 - On the next window, fill out the required fields as highlighted
170 below and click on “Create Repository” to create your local docker
171 registry (NOTE: you can see that the HTTP port is at 8082, which
172 will be your local docker registry port)
176 Setting up Eclipse Java EE & Importing the ONAP Maven Projects
177 --------------------------------------------------------------
179 - As root, open up Eclipse (preference is to create a new workspace):
184 cd <ECLIPSE_BIN_FOLDER>
187 - Set up general Eclipse configuration as below:
189 - Go to Window --> Preferences
191 - On the left side of the pop up window, go to Maven --> User
192 Settings. In the text box, add the maven settings for this project
193 (pointing at the https://nexus.onap.org repositories), then click
194 on Update Settings --> Apply --> OK
198 - Go to Maven --> Installations, then “Add…” the downloaded Apache
199 Maven (tested with 3.3.9) since the embedded maven installation has
200 been known to cause build failures on occasions.
204 - Go to Java --> Installed JREs, then “Add...” the downloaded Java 8
205 OpenJDK (usually located on /usr/lib/jvm/java-8-openjdk-amd64) as a
210 - Repeat the same steps below for APPC & deployment repos:
212 - Go to File --> Import… --> Maven --> Select Existing Maven
217 - Pick the folder where you cloned the git repository
219 - Checking the “Add project(s) to working set” and defining a new
220 working set name is suggested to separate multiple git repositories
224 Initial build of the APPC Core Maven Project
225 ---------------------------------------------
227 This section will guide you on the steps to take in order to compile the
228 APPC Core Project into your local maven repository (usually located on
229 the /root/.m2/repository path).
231 - On the Package Explorer, right click on the APPC Core package and go
232 to Run As --> Run Configurations…
234 - In the Run Configurations window, select Maven Build on the left side
235 & click on the “New” button. Set up your maven build configuration as
236 follows (relevant parts are highlighted):
240 - NOTE: In the above figure, it is recommended to uncheck the “Skip
241 Tests” option to run the test cases of the APPC Core Package to make
242 sure that APPC Core Features are tested beforehand.
244 - Make sure that you are pointing to the previously installed Java 8:
248 - For debugging purposes, it helps to output all build maven logs
249 generated to a file where you can check for any errors:
253 - Finally, click on “Run.” Assuming the build was successful and
254 without any issues, this will build and compile the APPC Core
255 Project and output the compiled artifacts to the default maven
256 repository (usually at /root/.m2/repository).
258 Deploying the APPC Core Maven Artifacts to Local Nexus 2 Repository
259 --------------------------------------------------------------------
261 Now that the APPC Core Project has been locally compiled by downloading
262 the APPC Core artifacts from the LF Nexus 2 Repository
263 (https://nexus.onap.org) in the previous section, we can go ahead and
264 deploy/upload these locally compiled APPC Core artifacts into the
265 active local Nexus 2 Repository (http://localhost:8081/nexus).
267 - You can use the same maven build item that was created in the
268 previous section “Initial building of the APPC Core Maven Project”
269 but just change the maven goal from “clean install” to “clean deploy”
271 - Make sure that the snapshot repository in the APPC Core’s rootpom
272 file (appc/pom.xml) is correctly configured to point to the maven
273 settings’s authentication credentials of the local Nexus 2 OSS (by
274 default, it is deployment/deployment123). If not, then the upload
275 will fail with an Unauthorized error since it will try to default to
276 uploading to the LF Nexus 2 OSS Repository instead:
280 - You can now run the maven build in the Run Configurations window.
282 - Once your build is successful, check that all of the intended APPC
283 Core maven artifacts have been successfully uploaded to your local
284 Nexus 2 OSS by going on the snapshot repository (located on
285 http://localhost:8081/nexus/content/repositories/snapshots/org/onap/appc)
287 - Now that the APPC Core maven artifacts are hosted and deployed on
288 your local Nexus 2 OSS Repository, you can compile and deploy the
289 APPC Deployment Repository in the next two sections.
291 Initial build of the APPC Deployment Maven Project
292 ---------------------------------------------------
294 This section will guide you on the steps to take in order to compile the
295 APPC Deployment Project into your local maven repository (usually
296 located on the /root/.m2/repository path). This builds & compiles the
297 artifacts necessary to build an APPC Docker Image on top of a base
298 SDNC Docker Image, inheriting the SDNC Docker Image configuration and
299 data, as well as the APPC data needed to deploy the APPC Docker Suite
300 that contains all that is necessary to deploy and install all of the
301 APPC Platform and its features.
303 - On the Package Explorer, right click on the APPC Deployment package
304 and go to Run As à Run Configurations…
306 - In the Run Configurations window, select Maven Build on the left side
307 & click on the “New” button. Set up your maven build configuration as
308 follows (relevant parts are highlighted):
312 - Make sure that you are pointing to the previously installed Java 8:
316 - For debugging purposes, it helps to output all build maven logs
317 generated to a file where you can check for any errors:
321 - Finally, click on “Run.” Assuming the build was successful and
322 without any issues, this will build and compile the APPC Core
323 Project and output the compiled APPC Deployment maven artifacts to
324 the default local maven repository (usually at /root/.m2/repository).
326 Deploying the APPC Deployment Maven Artifacts to Nexus 2 and Docker Image to Nexus 3 Repositories
327 --------------------------------------------------------------------------------------------------
329 *IMPORTANT: Make sure that you have created a local docker registry in
330 your local Nexus 3 OSS Repository before trying the steps below.*
332 Now that the APPC Deployment Project has been locally compiled into
333 your local maven repository (usually at /root/.m2/repository) by
334 downloading the APPC Deployment artifacts from the LF Nexus 2
335 Repository (https://nexus.onap.org) in the previous section, we can go
336 ahead and deploy/upload these locally compiled APPC Deployment
337 artifacts into the active local Nexus 2 Repository
338 (http://localhost:8081/nexus) as well as building and deploying the
339 APPC Docker Image into your local docker registry (localhost:8082). The
340 key item that enables this maven project to be able to
341 build/manipulate/upload the docker image into a specified location is
342 powered by the Docker Maven Plugin defined in the
343 appc-docker-project/installation/appc/pom.xml file, in which a “docker”
344 maven profile is defined which has the configuration necessary to build
345 the APPC Docker Image. More information on this maven docker plugin can
346 be found on https://dmp.fabric8.io/.
348 - Make sure that the snapshot repository in the APPC Deployment’s
349 rootpom file (appc-docker-project/pom.xml) is correctly configured to
350 point to the maven settings’s authentication credentials of the local
351 Nexus 2 OSS (by default, it is deployment/deployment123). If not,
352 then the upload will fail with an Unauthorized error since it will
353 try to default to uploading to the LF Nexus 2 OSS Repository instead:
357 - Go to the Run Configurations window. You can either add/modify a few
358 more properties on the same maven build configuration that was
359 created in the previous section “Initial build of the APPC
360 Deployment Maven Project” or just create a new maven build
361 configuration. The additional properties and maven goal change are
366 - From the new maven build configuration below, the following
367 properties were added to be able to download the dependent SDNC
368 Docker Image from LF Nexus 3 Docker Registry, as well as uploading
369 the finalized APPC Docker Image itself:
371 - docker.push.registry = localhost:8082 --> This is your local
372 docker registry location
374 - docker.push.username & docker.push.password --> Authentication
375 credentials to upload a docker image to the defined docker
378 - docker.pull.registry = nexus3.onap.org:10001 --> This is the LF
379 Nexus 3 docker registry location
381 - docker.pull.username & docker.pull.password --> Authentication
382 credentials to download a docker image from the defined docker
385 - altDeploymentRepository=openecomp-snapshot::default::http://localhost:8081/nexus/content/repositories/snapshots/
386 --> This serves as the alternative repository on which maven
387 artifacts should be deployed on in case that it was not defined in
388 . Therefore, this is optional.
390 - You can now run your maven build configuration.
392 - Once your build is successful, check that all of the intended APPC
393 Deployment maven artifacts have been successfully uploaded to your
394 local Nexus 2 OSS by going on the snapshot repository (located on
395 http://localhost:8081/nexus/content/repositories/snapshots/org/onap/appc).
396 Also, go to the Nexus 3 Docker Registry location in the
397 http://localhost:9081/#browse/browse/components:docker.local to make
398 sure that your APPC Docker Image has been uploaded.
400 - NOTE: In the docker registry location on the Nexus 3 OSS Website,
401 you should see the APPC Docker Image’s name as
402 “onap/appc-image” twice with different tags. The number of
403 tags for the image will be decided by what is defined on the
404 docker maven plugin’s section (note that there are properties to
405 be defined in the tags section)
409 - As you change the tag names as more tags are uploaded on your
410 local docker registry, we have experienced scenarios where the
411 “latest” tag will not always be the actual latest version of the
412 image you last uploaded. This seems to be a Nexus 3 OSS issue that
413 the ONAP team is still investigating.
415 - Now that the APPC Deployment Maven artifacts are deployed in Nexus 2
416 OSS and the APPC Docker Image is deployed in the Nexus 3 OSS local
417 repositories, you are ready to test the docker image. There are
418 detailed steps to do this in either of the two APPC GIT Repositories
420 `README.md <https://gerrit.onap.org/r/gitweb?p=appc.git;a=blob;f=README.md;h=9024ed1f4aae36a072ee1f4610920e69ac1eaef5;hb=HEAD>`__
423 .. |image0| image:: images/image0.png
424 .. |image1| image:: images/image1.png
425 .. |image2| image:: images/image2.png
426 .. |image3| image:: images/image3.png
427 .. |image4| image:: images/image4.png
428 .. |image5| image:: images/image5.png
429 .. |image6| image:: images/image6.png
430 .. |image7| image:: images/image7.png
431 .. |image8| image:: images/image8.png
432 .. |image9| image:: images/image9.png
433 .. |image10| image:: images/image10.png
434 .. |image11| image:: images/image11.png
435 .. |image12| image:: images/image12.png
436 .. |image13| image:: images/image13.png
437 .. |image14| image:: images/image14.png
438 .. |image15| image:: images/image15.png
439 .. |image16| image:: images/image16.png
440 .. |image17| image:: images/image17.png
441 .. |image18| image:: images/image18.png