docs/0_Getting_Started/5_Setting_Up_a_Docker_Container/Docker_Container_Setup.md

   1 ---
   2 edit_link: ''
   3 title: Overview
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/getting-started/docker-container-setup.md
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/getting_started/master/image-development-workflow-getting-started-book.yml -->
   9
  10 # Overview
  11
  12 This section explains how to quickly setup a Docker container environment
  13 suitable for using the Yocto Project build system.
  14 Within the container environment you can build images using BitBake
  15 and create and package AGL applications with a Software Development
  16 Kit (SDK) specifically tailored for your target hardware.
  17
  18 Docker is an open source tool designed to make it easier to create, deploy,
  19 and run applications by using containers.
  20 Containers allow a developer to package up an application with all
  21 the parts it needs, such as libraries and other dependencies, and ship
  22 it all out as one package.
  23
  24 The container you set up here is configured for Yocto Project and AGL.
  25 This configuration means you do not have to have a native Linux build
  26 host.
  27 You can use a system running Microsoft or MacOS.
  28
  29 You can learn more about Docker on the
  30 [Docker Documentation](https://docs.docker.com/) site.
  31
  32 **NOTE:** The information in this section has been tested using a Linux
  33 system.
  34 However, as previously mentioned, you could set up a Docker container
  35 that works using Windows or MacOS.
  36
  37 ## 1. Installing Docker Community Edition (CE)
  38
  39 If your build host does not already have
  40 [Docker CE](https://docs.docker.com/install/) installed, you must install it.
  41
  42 You can find general instructions for installing Docker CE on a Linux system
  43 on the [Docker Site](https://docs.docker.com/engine/installation/linux/).
  44
  45 You need to download the Docker CE version particular to your operating system.
  46 For example, if you are running the Ubuntu 16.04 Linux distribution, you can
  47 click the appropriate
  48 [Supported Platform](https://docs.docker.com/install/#supported-platforms) checkmark
  49 and see the instructions you need to install Docker CE on that platform.
  50
  51 Follow the steps to install Docker CE for your particular distribution.
  52 For example, the
  53 [Get Docker CE for Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
  54 page describes how to install Docker CE on a build host running the Ubuntu
  55 distribution.
  56
  57 Successful Docker installation is measured by the results of running a "hello world"
  58 application:
  59
  60 ```bash
  61 $ sudo docker run hello-world
  62 Hello from Docker!
  63 This message shows that your installation appears to be working correctly.
  64
  65 To generate this message, Docker took the following steps:
  66  1. The Docker client contacted the Docker daemon.
  67  2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
  68     (amd64)
  69  3. The Docker daemon created a new container from that image which runs the
  70     executable that produces the output you are currently reading.
  71  4. The Docker daemon streamed that output to the Docker client, which sent it
  72     to your terminal.
  73
  74 To try something more ambitious, you can run an Ubuntu container with:
  75  $ docker run -it ubuntu bash
  76
  77 Share images, automate workflows, and more with a free Docker ID:
  78  https://hub.docker.com/
  79
  80 For more examples and ideas, visit:
  81  https://docs.docker.com/get-started/
  82 ```
  83
  84 ## 2. Setting Up to Use Docker as a Non-Root User
  85
  86 For Linux machines, Docker runs as a root user by default.
  87 You can create a docker group and add yourself to it so that you do not
  88 have to preface every `docker` command with `sudo`, for example.
  89
  90 Follow the instructions on the
  91 [Post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/)
  92 page for information on how to create a Docker group and add yourself to the group.
  93
  94 Once you have set up to use Docker as a non-root user, you can log out of your
  95 system, log back in, and run the "hello world" application again to verify you
  96 do not have to use root:
  97
  98 ```bash
  99 $ docker run hello-world
 100 Hello from Docker!
 101 This message shows that your installation appears to be working correctly.
 102
 103 To generate this message, Docker took the following steps:
 104  1. The Docker client contacted the Docker daemon.
 105  2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 106     (amd64)
 107  3. The Docker daemon created a new container from that image which runs the
 108     executable that produces the output you are currently reading.
 109  4. The Docker daemon streamed that output to the Docker client, which sent it
 110     to your terminal.
 111
 112 To try something more ambitious, you can run an Ubuntu container with:
 113  $ docker run -it ubuntu bash
 114
 115 Share images, automate workflows, and more with a free Docker ID:
 116  https://hub.docker.com/
 117
 118 For more examples and ideas, visit:
 119  https://docs.docker.com/get-started/
 120 ```
 121
 122 ## 3. Setting Up a Persistent Workspace
 123
 124 Docker images are pre-configured to use a particular User Identifier (uid) and
 125 Group Identifier (gid) that allow the Container to use the Yocto Project
 126 build system.
 127 The `uid:gid` provides a dedicated user account *devel*,
 128 which belongs to `uid=1664(devel)` and `gid=1664(devel)`.
 129
 130 **NOTE:** The password is `devel`.
 131
 132 The `create_container.sh` script as shown in the following
 133 section instantiates a new container and shares the following
 134 volumes with the build host:
 135
 136 * **/xdt:**
 137   The build directory inside the container.
 138   This directory is stored in **~/ssd/xdt_$ID**, which is specific to
 139   the container's instance ID.
 140
 141 * **/home/devel/mirror:**
 142   A development mirror stored in **~/ssd/localmirror_$ID**,
 143   which is specific to the container's instance ID.
 144
 145 * **/home/devel/share:**
 146   A development share at **~/devel/docker/share**, which is shared
 147   by all containers.
 148
 149 These shared volumes need the proper permissions in order form them
 150 to be accessible from the container environment.
 151 You can make sure permissions are in order using the following commands:
 152
 153 ```bash
 154 $ mkdir ~/ssd ~/devel
 155 $ chmod a+w ~/ssd ~/devel
 156 ```
 157
 158 **Note**:
 159
 160 * To gain access from your host on files created within the container, your
 161    host account requires to be added to group id 1664.
 162
 163 ## 4. Getting the Generic AGL Worker Docker Image
 164
 165 You can either locate and install a pre-built image or rebuild the image.
 166
 167 ### Using a Pre-Built Image
 168
 169 Use the `wget` command to download the latest pre-built Docker image
 170 into your local Docker instance.
 171 Here is an example:
 172
 173 ```bash
 174 $ wget -O - https://download.automotivelinux.org/AGL/snapshots/sdk/docker/docker_agl_worker-latest.tar.xz | docker load
 175 $ docker images
 176       REPOSITORY                                      TAG                 IMAGE ID            CREATED             SIZE
 177       docker.automotivelinux.org/agl/worker-generic   5.99-95             6fcc19b4e0d7        2 weeks ago         1.56GB
 178       jenkins                                         latest              55720d63e328        5 weeks ago         711.9 MB
 179       hello-world                                     latest              c54a2cc56cbb        5 months ago        1.848 kB
 180 ```
 181
 182 After loading the image, identify and export the `IMAGE_ID`.
 183 For example, the `IMAGE_ID` given the previous command is "6fcc19b4e0d7".
 184
 185 ```bash
 186 $ export IMAGE_ID=6fcc19b4e0d7
 187 ```
 188
 189 ### Building an Image
 190
 191 You can build the Docker image using the
 192 [docker-worker-generator](https://git.automotivelinux.org/AGL/docker-worker-generator/)
 193 scripts.
 194
 195 ## 5. Starting the Container
 196
 197 After you have the image available, use the
 198 `create_container` script to start a new, fresh container that is
 199 based on the AGL Worker image:
 200
 201 **NOTE:**
 202 The password for the ID "devel" inside the docker image is "devel".
 203
 204 ```bash
 205 $ git clone https://git.automotivelinux.org/AGL/docker-worker-generator
 206 $ cd docker-worker-generator
 207 $ ./contrib/create_container 0 $IMAGE_ID
 208 $ docker ps
 209 CONTAINER ID        IMAGE                                       COMMAND                  CREATED             STATUS              PORTS                                                                                        NAMES
 210 4fb7c550ad75        6fcc19b4e0d7   "/usr/bin/wait_for_ne"   33 hours ago        Up 33 hours         0.0.0.0:2222->22/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:10809->10809/tcp   agl-worker-odin-0-sdx
 211 ```
 212
 213 ## 6. Installing the AGL SDK for Your Target
 214
 215 Once you have a new container that is based on the AGL Worker Image, you
 216 can copy the SDK Installer to the container and then install
 217 the target-specific AGL SDK.
 218 With an SDK installed, you are able to develop AGL applications
 219 using the SDK.
 220
 221 For this section, assume that the SDK is `agl-demo-platform-crosssdk` and was built
 222 according to the instructions in the
 223 "[Download or Build Your SDK Installer](./app-workflow-sdk.html)"
 224 section.
 225
 226 Follow these steps:
 227
 228 1. **Copy the SDK Installer to the Shared Volume:
 229
 230 <!--
 231
 232 This is part of the example from the original file.
 233 It shows building out the SDK from a container.
 234
 235 For example, we could have built the SDK from another worker container listening with SSH on port 2223:
 236
 237 ```bash
 238 create_container 1;
 239 ssh -p 2223 devel@mybuilder.local;
 240 ... [ prepare build environment ] ...
 241 bitbake agl-demo-platform-crosssdk;
 242 ... [ build happens in /xdt/build ] ...
 243 ```
 244 -->
 245
 246    ```
 247    $ cp /xdt/build/tmp/deploy/sdk/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-cortexa15hf-neon-toolchain-3.0.0+snapshot.sh ~/share
 248    ```
 249
 250 2. Log into your "SDK Container" and install the SDK:
 251
 252    ```bash
 253    $ ssh -p 2222 devel@mysdk.local
 254    $ install_sdk ~/share/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-cortexa15hf-neon-toolchain-3.0.0+snapshot.sh
 255    ```
 256
 257 ## 7. Build Your Application
 258
 259 Once you have the SDK installed in your container, you are ready
 260 to develop your application.
 261 See the
 262 "[Create and Build the Application](./app-workflow-build-app.html)"
 263 section for more information.
 264
 265
 266 <!--
 267
 268 This stuff is leftover from the original file.
 269 It is pretty generic and I don't think we need to retain it.
 270
 271 First, you must source the SDK environment you wish to use (you MUST repeat this step each time you open a new shell):
 272
 273 ```bash
 274 source /xdt/sdk/environment-setup-<your_target>
 275 ```
 276
 277 You're then ready to go: get the sources, run the builds ...
 278
 279 ```bash
 280 git clone <your repo for your app>;
 281 cd <your app>;
 282 cmake; make; make package;
 283 ```
 284
 285 -->