Building and Running APPC Docker Images

Owned by Patrick Brady
Last updated: Sept 13, 2019 by Takamune Cho
5 min read

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

  1. sudo groupadd docker

  2. sudo usermod -aG docker $USER

  3. sudo shutdown now -r


Test Docker install

You can test your install by running docker version



Setup proxy server for Docker

  1. Create a new directory for Docker service: sudo mkdir /etc/systemd/system/docker.service.d

  2. Create a new file in the new directory called “http-proxy.conf” with the following contents:



[Service] Environment=”HTTP_PROXY=<put proxy address here>/”



  1. Reload Docker

    1. sudo systemctl daemon-reload

    2. sudo systemctl restart docker

For Older Linux (Ubuntu 1404):

  1. Edit the file “/etc/default/docker”

  2. Uncomment the line that begins with “export http_proxy”

  3. Replace the proxy address on the same line with the address of your proxy server

  4. 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.

  1. By default, your maven settings file will be in your Linux home folder, in the .m2 folder (~/.m2/settings.xml)

  2. You’ll want to add a repository entry pointing to your local .m2/repository folder

  3. 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.

  1. First, you need to login Docker to the onap repository

    1. docker login nexus3.onap.org:10001

    2. Use your Linux Foundation credentials for the login

    3. Note: It appears that if you guess your password too many times, you will be locked out.

    4. Now we pull down the image

      1. 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

      2. Pull the image with: docker pull nexus3.onap.org:10001/onap/ccsdk-odlsli-alpine-image:0.4.1 (For Dublin Release)

      3. 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

  1. The first step is to build the main appc project.

    1. This must be done on the same system that you will be building the Docker image on

    2. Go to your appc folder in a terminal

    3. Run mvn clean install

  2. Once this has completed, we will do a Docker build on the deployment project

    1. Go to your deployment project folder in a terminal

    2. 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.

  1. 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.

  2. Open a terminal window in the “docker-compose” directory of the appc deployment git repository that you cloned earlier

  3. We want to slightly modify the docker-compose.yml file in this directory

    1. In the file, you will see a “dgbuilder:” line

    2. Remove this line and everything below it and save the file.

    3. 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

  4. From the same directory containing the docker-compose.yml file, run the command docker-compose up -d

    1. This will create and start up the appc Docker containers

  5. You can run the docker-compose logs command to see the startup log.

    1. Once the log displays the Opendaylight logo, you know startup is complete. It will take a few minutes.



Opening the Opendaylight api doc explorer

  1. From a browser on the same VM where you have Docker running:

  2. Go to http://localhost:8282/apidoc/explorer/index.html

  3. The username is "admin", password is "Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U"



Commands while running the Docker image

docker-compose logs

Shows the statup log for the containers. This is a good way to check if startup is complete.

docker ps

Shows all running Docker containers

docker ps -a

Shows all running and stopped Docker containers

docker stop <container name or id>

Stops a running Docker container

docker rm -v <container name or id>

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)

docker exec -it appc_controller_container bash

Opens the bash shell in the running appc Docker container. The exit command will allow you to leave the Docker container.

docker exec -it appc_controller_container /opt/opendaylight/current/bin/client -u karaf

Directly opens the opendaylight console that is running in the Docker container

docker images

List all of the Docker images that are on your system. Shows their name, version, id, size, and date.

docker rmi -f <docker image id>

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