Assumptions
This guide assumes the following:
- You have a Linux virtual machine where you are currently able to build the appc code
- Your virtual machine should have adequate resources to run the appc Docker images
- The Docker images can run in a virtual machine with 4GB of ram, but if you are also running Eclipse, it might be a good idea to configure 6GB or more
- You should give the virtual machine at least 2, possibly 3 or 4 processor cores
- Some of the steps in this guide may only work on newer versions of Linux. In this case, you may see a section in red which has steps to use for an older version.
Where to install Docker
You can either run Docker on the same VM that you are using for maven and other development work, or you can install Docker in its own VM. There is less network configuration to be done if Docker is installed in the same VM as your maven builds. In this guide, we will look at installing Docker in the same VM that you are using for builds.
Installing Docker Services
The Docker service is installed on Linux from the package manager. It is available for most Linux distributions.
Install on Ubuntu: sudo apt-get install docker.io
Install on Centos/Redhat: sudo yum install docker
Make sure Docker is set to start
sudo systemctl enable docker
sudo systemctl start docker
For older Linux versions (Ubuntu 1404):
sudo service docker start
Allow Docker to run without root
Note: This could be considered a security risk because your account will basically have root access when it’s in the docker group
sudo groupadd docker
sudo usermod -aG docker $USER
sudo shutdown now -r
Test Docker install
You can test your install by running docker version
Setup proxy server for Docker
- Create a new directory for Docker service:
sudo mkdir /etc/systemd/system/docker.service.d
- Create a new file in the new directory called “http-proxy.conf” with the following contents:
[Service] Environment=”HTTP_PROXY=<put proxy address here>/”
- Reload Docker
sudo systemctl daemon-reload
sudo systemctl restart docker
For Older Linux (Ubuntu 1404):
- Edit the file “/etc/default/docker”
- Uncomment the line that begins with “export http_proxy”
- Replace the proxy address on the same line with the address of your proxy server
- Restart Docker:
sudo service docker restart
Installing docker-compose
We normally use the docker-compose utility to bring up the appc Docker images.
It can be installed with: sudo apt-get install docker-compose
Depending on your Linux version and repository setup, docker-compose may not be available from the package manager.
- Python pip can also be used to install docker compose:
sudo pip install docker-compose
- If pip is not installed, it should be able to be installed with:
sudo apt-get install python-pip
- The full install guide for docker-compose can be found on the Docker website: https://docs.docker.com/compose/install/
Preparing for Docker Build in Maven
You need to make sure that you have an entry in your maven “settings.xml” file for your local maven repository. This way, when you run the Docker build, it will be able to download the appc installers from your local computer instead of going out to nexus server.
- By default, your maven settings file will be in your Linux home folder, in the .m2 folder (~/.m2/settings.xml)
- You’ll want to add a repository entry pointing to your local .m2/repository folder
- The local repository entry looks like the following, it should go in the <repositories> tag in the settings file. You need to put your Linux user id in the placeholder.
<repository> <id>local-maven</id> <name>local-maven</name> <url>file:///home/<Linux user id>/.m2/repository</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>local-maven</id> <name>local-maven</name> <url>file:///home/<Linux user id>/.m2/repository</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </pluginRepository>
Cloning the appc deployment project
The appc deployment project contains the maven files which will build the Docker image.
Clone this repository. (git clone
https://gerrit.onap.org/r/appc/deployment)
Downloading the pre-requisite Docker images
Our appc image is based on the ccsdk odlsli Docker image. So we need to download this before building the appc Docker image.
- First, you need to login Docker to the onap repository
docker login nexus3.onap.org:10001
- Use your Linux Foundation credentials for the login
- Note: It appears that if you guess your password too many times, you will be locked out.
- Now we pull down the image
- At the time of this writing, the latest version of the ccsdk-odlsli-image is “v0.1.0”, but this could change in the future
- Pull the image with:
docker pull nexus3.onap.org:10001/onap/ccsdk-odlsli-alpine-image:0.4.1 (For Dublin Release)
- Once it is done, we need to tag this image with the correct name that the appc build will be expecting:
docker tag nexus3.onap.org:10001/onap/ccsdk-odlsli-alpine-image:0.4.1 onap/ccsdk-odlsli-alpine-image:0.4.1
Building with Maven on the command line
- The first step is to build the main appc project.
- This must be done on the same system that you will be building the Docker image on
- Go to your appc folder in a terminal
- Run
mvn clean install
- Once this has completed, we will do a Docker build on the deployment project
- Go to your deployment project folder in a terminal
mvn clean install -P docker
Checking that the new Docker image was created
The command docker images
will show all the Docker images that you have on your system. You should see an image called “onap/appc-image” that was created recently (when you ran the build).
Starting the new Docker image
Note: Starting up the Docker containers from behind a proxy server usually does not work. We have had several experimental methods to make it work, but none have proven to be reliable.
- By default, the docker-compose command will use the “docker-compose.yml” file from the current directory that you run the command from as its configuration.
- Open a terminal window in the “docker-compose” directory of the appc deployment git repository that you cloned earlier
- We want to slightly modify the docker-compose.yml file in this directory
- In the file, you will see a “dgbuilder:” line
- Remove this line and everything below it and save the file.
- Note: If you plan to use the dg-builder, you will want to skip this step. But, if you don’t plan to use it, it will save time and memory to remove it
- From the same directory containing the docker-compose.yml file, run the command
docker-compose up -d
- This will create and start up the appc Docker containers
- You can run the
docker-compose logs
command to see the startup log.- Once the log displays the Opendaylight logo, you know startup is complete. It will take a few minutes.
Opening the Opendaylight api doc explorer
- From a browser on the same VM where you have Docker running:
- Go to http://localhost:8282/apidoc/explorer/index.html
- The username is "admin", password is "Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U"
Commands while running the Docker image
| Shows the statup log for the containers. This is a good way to check if startup is complete. |
| Shows all running Docker containers |
| Shows all running and stopped Docker containers |
| Stops a running Docker container |
| Deletes a Docker container and its associated volume (does not delete the Docker image that was used to bring up the container) |
docker ps | while read a b c d e f g; do docker stop $a; done | This will stop all running Docker containers |
docker ps -a | while read a b c d e f g; do docker rm -v $a; done | This will delete all created Docker containers (will not delete the Docker image files) |
| Opens the bash shell in the running appc Docker container. The exit command will allow you to leave the Docker container. |
| Directly opens the opendaylight console that is running in the Docker container |
| List all of the Docker images that are on your system. Shows their name, version, id, size, and date. |
| Delete the Docker image off your system with the given image id |
Accessing the MySQL database Docker container
Once the Docker containers are running, you can directly access the mysql database with this command: docker exec -it sdnc_db_container mysql -uroot -popenECOMP1.0
16 Comments
Mandeep Khinda
Hi Patrick Brady What does your full settings.xml look like? I am using the one found here: https://wiki.onap.org/download/attachments/15997820/settings.xml?version=1&modificationDate=1506156303000&api=v2 with a local repo added as its own profile and when I follow the build instructions above, the resulting docker image does not include my locally built jars/zips but the ones it downloads from nexus.
Also, as of today my maven build on amsterdam 1.2.1-SNAPSHOT started failing in the IaaS Adapter - bundle. Very strange that it can no longer pick up the org.mockito dependency. I worked around it by adding that depenency to the pom of that project. No clue what is going on here as it has happened in multiple environments (mac laptop, ubuntu vm). Has this happened to you before?
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:2.5.1:testCompile (default-testCompile) on project appc-iaas-adapter-bundle: Compilation failure: Compilation failure:
[ERROR] /Users/mkhinda/appc/appc/appc-adapters/appc-iaas-adapter/appc-iaas-adapter-bundle/src/test/java/org/openecomp/appc/adapter/iaas/impl/TestServiceCatalog.java:[42,18] error: package org.mockito does not exist
[ERROR] /Users/mkhinda/appc/appc/appc-adapters/appc-iaas-adapter/appc-iaas-adapter-bundle/src/test/java/org/openecomp/appc/adapter/iaas/impl/TestServiceCatalog.java:[90,53] error: cannot find symbol
[ERROR] symbol: variable Mockito
[ERROR] location: class TestServiceCatalog
[ERROR] /Users/mkhinda/appc/appc/appc-adapters/appc-iaas-adapter/appc-iaas-adapter-bundle/src/test/java/org/openecomp/appc/adapter/iaas/impl/TestServiceCatalog.java:[90,18] error: cannot find symbol
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
[ERROR]
[ERROR] After correcting the problems, you can resume the build with the command
[ERROR] mvn <goals> -rf :appc-iaas-adapter-bundle
Patrick Brady
I think the Mockito dependency issue was a known issue that caused problems on non-Jenkins builds of Amsterdam. It has been fixed on the master (Beijing) code branch.
Patrick Brady
If your appc/deployment build is pulling artifacts from nexus instead of locally, it probably means that the ones on nexus are more recent. The most recent version of a snapshot artifact will always be used. So, if the Jenkins jobs ran and put artifacts in nexus more recently than you ran the local build of appc, it will take the ones from nexus.
Mandeep Khinda
Cool thanks for the reply - I will try that out.
I just ran into something else. After running the mvn install command in the deployment project to build my docker image, a maven plugin runs that adds a license header into files. It seems to add them into everything including DG jsons source code which then cause them all to fail on startup. Has that been fixed on master too?
I wanted to test out amsterdam but maybe I should switch it to master? Would I run into other problems if I use appc from master and the rest of my onap components from Amsterdam? Doesn't seem right to me. I'll look for that fix on master and see if I can back-port it locally.
EDIT>>> Just found APPC-160 and APPC-293. Looks like on Amsterdam this is still a problem if you build locally.
Mandeep Khinda
So I checked and here is what is happening to my build. It tries all my repos including the local one but it ends up selecting the remote one because my local repo doesn't have a maven-metadata.xml file but has a maven-metadata-local.xml and so it defaults to the remote one... This is getting into some advanced maven stuff I haven't dealt with before.. Good learning experience for me. It is all happening in the installZips.sh script. There is a mvn command there and I am not sure how to get it to use the local repo and not the remote one. Any idea?
UPDATE >>>> I tried adding the offline option to lines 89, 95, and 99 of installZips.sh and it worked (mvn -o). It only looked locally and picked up my snapshot jars in the docker image. That might be a fix for this.
Patrick Brady
The maven commands in installZips should use your local maven settings.xml file.
As for the issue with the license getting added in, I am submitting a fix for that in master branch. APPC-562 - Getting issue details... STATUS
Takamune Cho
use "sudo docker login -u docker -p docker nexus.onap.org:10001" is good also
Arindam Mondal
After I do "
mvn clean install -P docker"
I'm getting below error[ERROR] DOCKER> Unable to build image [onap/appc-cdt-image]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] appc-deployment .................................... SUCCESS [ 2.448 s]
[INFO] Platform Logic ..................................... SUCCESS [ 0.082 s]
[INFO] Platform Logic : APP-C ............................. SUCCESS [ 0.152 s]
[INFO] Platform Logic Installer for APP-C ................. SUCCESS [ 0.727 s]
[INFO] Installation ....................................... SUCCESS [ 0.133 s]
[INFO] Installation - APPC Docker ......................... SUCCESS [03:07 min]
[INFO] Installation - CDT Docker .......................... FAILURE [ 21.663 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 03:33 min
[INFO] Finished at: 2018-06-29T15:25:37+09:00
[INFO] Final Memory: 63M/544M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.fabric8:docker-maven-plugin:0.16.5:build (generate-images) on project installation-cdt: Unable to build image [onap/appc-cdt-image]: lstat config-design-tool: no such file or directory -> [Help 1]
[ERROR]
Takamune Cho
you need to go to cdt repo, run "
mvn clean install
" before run "mvn clean install -P docker" on deployment repoMary Smith
I am getting the error: Error response from daemon: Get https://nexus3.onap.org:10001/v1/users/: dial tcp 199.204.45.137:10001: getsockopt: connection refused
after the command 'docker login nexus3.onap.org:10001'; the same error using 'sudo docker login -u docker -p docker nexus.onap.org:10001'.
'docker version' command returned the following responses,
Client: Version: 17.03.2-ce API version: 1.27 Go version: go1.6.2 Git commit: f5ec1e2 Built: Thu Jul 5 23:07:48 2018 OS/Arch: linux/amd64
Server: Version: 17.03.2-ce API version: 1.27 (minimum version 1.12) Go version: go1.6.2 Git commit: f5ec1e2 Built: Thu Jul 5 23:07:48 2018 OS/Arch: linux/amd64 Experimental: false
Any suggestion?
Thanks.
Mary Smith
Sorry, I hate to answer my own question; my issue is resolved.
Takamune Cho
OK good to hear
Liu Yongqiang
hi, seems not any introduction for the docker hub image onap/appc-image. could any one write a guide for usage of this image?
Takamune Cho
The ONAP docker image in docker hub is a copy from nexus server in ONAP. You would follow up OOM (k8s) setup and change
Repository: nexus3.onap.org:10001
image: onap/appc-image:1.5.3
in value.yaml file
point to docker hub.
This is my assumption. I never tried this before. but I assume that should work
Liu Yongqiang
such error when I build docker images(mvn clean install -P docker -DskipTests | tee -a appc-deployment-docker-image-build.log):
Downloaded from 60_opendaylight-mirror: https://nexus.opendaylight.org/content/repositories/public/com/google/guava/guava/23.0-android/guava-23.0-android.jar (2.5 MB at 1.0 MB/s)
[INFO] Building tar: /root/ONAP-APPC/deployment/installation/appc/target/docker/onap/appc-image/tmp/docker-build.tar
[INFO] DOCKER> [onap/appc-image:latest]: Created docker-build.tar in 4 seconds
[ERROR] DOCKER> Unable to build image [onap/appc-image] : "The command '/bin/sh -c apk add --no-cache procps' returned a non-zero code: 127" ["The command '/bin/sh -c apk add --no-cache procps' returned a non-zero code: 127" ]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for appc-deployment 1.6.0-SNAPSHOT:
[INFO]
[INFO] appc-deployment .................................... SUCCESS [ 5.873 s]
[INFO] Platform Logic ..................................... SUCCESS [ 0.221 s]
[INFO] Platform Logic : APP-C ............................. SUCCESS [ 0.355 s]
[INFO] Platform Logic Installer for APP-C ................. SUCCESS [ 1.145 s]
[INFO] Installation ....................................... SUCCESS [ 0.126 s]
[INFO] Installation - APPC Docker ......................... FAILURE [04:05 min]
[INFO] Installation - CDT Docker .......................... SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 04:15 min
[INFO] Finished at: 2019-07-15T07:14:37Z
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.fabric8:docker-maven-plugin:0.28.0:build (generate-images) on project installation-appc: Unable to build image [onap/appc-image] : "The command '/bin/sh -c apk add --no-cache procps' returned a non-zero code: 127" -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
[ERROR]
[ERROR] After correcting the problems, you can resume the build with the command
[ERROR] mvn <goals> -rf :installation-appc
Takamune Cho
can you do "apk add --no-cache procps" in Alpine docker image manually from your local env? something it failed to add procps package for APPC Alpine image.