doc/developer/building-docker.rst

   1 Docker
   2 ======
   3
   4 This page covers how to build FRR Docker images.
   5
   6 Images
   7 """"""
   8 FRR has Docker build infrastructure to produce Docker images containing
   9 source-built FRR on the following base platforms:
  10
  11 * Alpine
  12 * Centos 7
  13 * Centos 8
  14
  15 The following platform images are used to support Travis CI and can also
  16 be used to reproduce topotest failures when the docker host is Ubuntu
  17 (tested on 18.04 and 20.04):
  18
  19 * Ubuntu 18.04
  20 * Ubuntu 20.04
  21
  22 The following platform images may also be built, but these simply install a
  23 binary package from an existing repository and do not perform source builds:
  24
  25 * Debian 10
  26
  27 Some of these are available on `DockerHub
  28 <https://hub.docker.com/repository/docker/frrouting/frr/tags?page=1>`_.
  29
  30 There is no guarantee on what is and is not available from DockerHub at time of
  31 writing.
  32
  33 Scripts
  34 """""""
  35
  36 Some platforms contain an included build script that may be run from the host.
  37 This will set appropriate packaging environment variables and clean up
  38 intermediate build images.
  39
  40 These scripts serve another purpose. They allow building platform packages
  41 without needing the platform. For example, the Centos 8 docker image can also
  42 be leveraged to build Centos 8 RPMs that can then be used separately from
  43 Docker.
  44
  45 If you are only interested in the Docker images and don't want the cleanup
  46 functionality of the scripts you can ignore them and perform a normal Docker
  47 build. If you want to build multi-arch docker images this is required as the
  48 scripts do not support using Buildkit for multi-arch builds.
  49
  50 Building Alpine Image
  51 ---------------------
  52
  53 Script::
  54
  55    ./docker/alpine/build.sh
  56
  57 No script::
  58
  59    docker build -f docker/alpine/Dockerfile .
  60
  61 No script, multi-arch (ex. amd64, arm64, armv7)::
  62
  63    docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -f docker/alpine/Dockerfile -t frr:latest .
  64
  65
  66 Building Debian Image
  67 ---------------------
  68
  69 ::
  70
  71    cd docker/debian
  72    docker build .
  73
  74 Multi-arch (ex. amd64, arm64, armv7)::
  75
  76    cd docker/debian
  77    docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t frr-debian:latest .
  78
  79 Building Centos 7 Image
  80 -----------------------
  81
  82 Script::
  83
  84    ./docker/centos-7/build.sh
  85
  86 No script::
  87
  88    docker build -f docker/centos-7/Dockerfile .
  89
  90 No script, multi-arch (ex. amd64, arm64)::
  91
  92    docker buildx build --platform linux/amd64,linux/arm64 -f docker/centos-7/Dockerfile -t frr-centos7:latest .
  93
  94
  95 Building Centos 8 Image
  96 -----------------------
  97
  98 Script::
  99
 100    ./docker/centos-8/build.sh
 101
 102 No script::
 103
 104    docker build -f docker/centos-8/Dockerfile .
 105
 106 No script, multi-arch (ex. amd64, arm64)::
 107
 108    docker buildx build --platform linux/amd64,linux/arm64 -f docker/centos-8/Dockerfile -t frr-centos8:latest .
 109
 110
 111
 112 Building ubi 8 Image
 113 -----------------------
 114
 115 Script::
 116
 117    ./docker/ubi-8/build.sh
 118
 119 Script with params, an example could be this (all that info will go to docker label) ::
 120
 121    ./docker/ubi-8/build.sh  frr:ubi-8-my-test "$(git rev-parse --short=10 HEAD)" my_release my_name my_vendor
 122
 123 No script::
 124
 125    docker build -f docker/ubi-8/Dockerfile .
 126
 127 No script, multi-arch (ex. amd64, arm64)::
 128
 129    docker buildx build --platform linux/amd64,linux/arm64 -f docker/ubi-8/Dockerfile -t frr-ubi-8:latest .
 130
 131
 132
 133 Building Ubuntu 18.04 Image
 134 ---------------------------
 135
 136 Build image (from project root directory)::
 137
 138    docker build -t frr-ubuntu18:latest  -f docker/ubuntu18-ci/Dockerfile .
 139
 140 Start the container::
 141
 142    docker run -d --privileged --name frr-ubuntu18 --mount type=bind,source=/lib/modules,target=/lib/modules frr-ubuntu18:latest
 143
 144 Running a topotest (when the docker host is Ubuntu)::
 145
 146    docker exec frr-ubuntu18 bash -c 'cd ~/frr/tests/topotests/ospf-topo1 ; sudo pytest test_ospf_topo1.py'
 147
 148 Starting an interactive bash session::
 149
 150    docker exec -it frr-ubuntu18 bash
 151
 152 Stopping an removing a container::
 153
 154    docker stop frr-ubuntu18 ; docker rm frr-ubuntu18
 155
 156 Removing the built image::
 157
 158    docker rmi frr-ubuntu18:latest
 159
 160
 161 Building Ubuntu 20.04 Image
 162 ---------------------------
 163
 164 Build image (from project root directory)::
 165
 166    docker build -t frr-ubuntu20:latest  -f docker/ubuntu20-ci/Dockerfile .
 167
 168 Start the container::
 169
 170    docker run -d --privileged --name frr-ubuntu20 --mount type=bind,source=/lib/modules,target=/lib/modules frr-ubuntu20:latest
 171
 172 Running a topotest (when the docker host is Ubuntu)::
 173
 174    docker exec frr-ubuntu20 bash -c 'cd ~/frr/tests/topotests/ospf-topo1 ; sudo pytest test_ospf_topo1.py'
 175
 176 Starting an interactive bash session::
 177
 178    docker exec -it frr-ubuntu20 bash
 179
 180 Stopping an removing a container::
 181
 182    docker stop frr-ubuntu20 ; docker rm frr-ubuntu20
 183
 184 Removing the built image::
 185
 186    docker rmi frr-ubuntu20:latest