bootstrap/README.md

   1 # Samba Bootstrap
   2
   3 A pure python3 module with CLI to bootstrap Samba envs for multiple distributions.
   4
   5 ## Features
   6
   7 - manage Samba dependencies list for multiple distributions
   8 - render dependencies package list to bootstrap shell scripts(apt, yum and dnf)
   9 - render Vagrantfile to provision virtual machines with bootstrap scripts
  10 - render Dockerfile to build docker images with bootstrap scripts
  11 - build/tag/push docker images
  12
  13 ## Supported Distributions
  14
  15 deb: Debian 10, Ubuntu 1604|1804|2004
  16 rpm: CentOS 7|8, Fedora 33|34, openSUSE Leap 15.1|15.2
  17
  18 Easy to add more.
  19
  20 ## Usage
  21
  22 Render files:
  23
  24  bootstrap/template.py --render
  25
  26 Files are rendered into `bootstrap/generated-dists` directory in current dir.
  27 It also generates bootstrap/sha1sum.txt and prints out the sha1sum of the
  28 current code/configuration.
  29
  30 Just calculate the sha1sum for consistency checks:
  31
  32  bootstrap/template.py --sha1sum
  33
  34 The checksum needs to be added as `SAMBA_CI_CONTAINER_TAG` in
  35 the toplevel .gitlab-ci-main.yml file.
  36
  37 NOTE: Remember to remove any files not tracked by git from the bootstrap
  38 directory before running bootstrap/template.py.
  39
  40   git clean -dfx bootstrap
  41
  42 Otherwise the files will affect the checksum but because they are not
  43 checked in and won't be pushed to CI system the checksum calculated there
  44 won't match.
  45
  46 ## User Stories
  47
  48 As a gitlab-ci user, I can use this tool to build new CI docker images:
  49
  50  After committing the result of calling `bootstrap/template.py --render`
  51  and updating `SAMBA_CI_CONTAINER_TAG` in .gitlab-ci.yml, you can push.
  52
  53  But you need to pass `SAMBA_CI_REBUILD_IMAGES=yes` as environment
  54  variable. It means the pipeline runs the 'images' stage and builds
  55  the new container images for all supported distributions and
  56  uploads the images into the registry.gitlab.com/samba-team/devel/samba
  57  container registry.
  58
  59  You can push by specifying the variable (note multiple -o options are allowed,
  60  see https://docs.gitlab.com/ee/user/project/push_options.html):
  61
  62   `git push -o ci.variable='SAMBA_CI_REBUILD_IMAGES=yes' git@gitlab.com:samba-team/devel/samba.git ...`
  63
  64  If you want to try to build images for the (currently) broken
  65  distributions, you would pass `SAMBA_CI_REBUILD_BROKEN_IMAGES=yes`
  66  in addition to the custom pipeline. Note the images for
  67  the broken distributions are just build, but not uploaded
  68  to the container registry. And any failures in the image
  69  creation is ignored. Once you managed to get success, you should
  70  move from `.build_image_template_force_broken` to `.build_image_template`.
  71  And also add a `.samba-o3-template` job for the new image
  72  in the main .gitlab-ci.yml file.
  73
  74  Over time we'll get a lot of images pushed to the container registry.
  75  The approach we're using allows gitlab project maintainers to
  76  remove old images! But it is possible to regenerate the images
  77  if you have the need to run a gitlab ci pipeline based on an
  78  older branch.
  79
  80 As a Samba developer/tester, I can setup a Samba env very quickly.
  81
  82 With Docker:
  83
  84  cd ~/samba
  85  git clean -xdf
  86  docker login
  87  docker pull registry.gitlab.com/samba-team/devel/samba/samba-ci-ubuntu1804:${sha1sum}
  88  docker run -it -v $(pwd):/home/samba/samba samba-ci-ubuntu1804:${sha1sum} bash
  89
  90 With podman:
  91
  92   podman run -ti --cap-add=SYS_PTRACE --security-opt seccomp=unconfined registry.gitlab.com/samba-team/devel/samba/samba-ci-ubuntu1804:${sha1sum} bash
  93
  94 With Vagrant:
  95
  96  cd bootstrap/generated-dists/
  97  vagrant up   # start all
  98  vagrant up debian10  # start one
  99  vagrant ssh debian10
 100  vagrant destroy debian10  # destroy one
 101  vagrant destroy  # destroy all
 102
 103 Or a remote/cloud machine:
 104
 105  scp bootstrap/generated-dists/fedora33/bootstrap.sh USER@IP:
 106  ssh USER@IP
 107  sudo bash ./bootstrap.sh
 108