3d22ab136a0066e470ed96d6ffc30298933d0671
[samba.git] / bootstrap / READMD.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 boostrap shell scripts(apt, yum and dnf)
9 - render Vagrantfile to provision vitual 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 7|8|9, Ubuntu 1404|1604|1804
16 rpm: CentOS 6|7, Fedora 28|29, openSUSE Leap 15.0
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.yml file.
36
37 ## User Stories
38
39 As a gitlab-ci user, I can use this tool to build new CI docker images:
40
41  After committing the result of calling `bootstrap/template.py --render`
42  and updating `SAMBA_CI_CONTAINER_TAG` in .gitlab-ci.yml, you can push
43  The branch to git@gitlab.com:samba-team/devel/samba.git using:
44
45   git push -o ci.skip git@gitlab.com:samba-team/devel/samba.git ...
46
47  The `-o ci.skip` option means gitlab won't start a pipeline
48  for the just pushed branch.
49
50  Instead you would start a custom pipeline at:
51
52   https://gitlab.com/samba-team/devel/samba/pipelines/new
53
54  But you need to pass `SAMBA_CI_REBUILD_IMAGES=yes` as environment
55  variable. It means the pipeline runs the 'images' stage and builds
56  the new container images for all supported distributions and
57  uploads the images into the registry.gitlab.com/samba-team/devel/samba
58  container registry.
59
60  If you want to try to build images for the (currently) broken
61  distributions, you would pass `SAMBA_CI_REBUILD_BROKEN_IMAGES=yes`
62  in addition to the custom pipeline. Note the images for
63  the broken distributions are just build, but not uploaded
64  to the container registry. And any failures in the image
65  creation is ignored. Once you managed to get success, you should
66  move from `.build_image_template_force_broken` to `.build_image_template`.
67  And also add a `.samba-o3-template` job for the new image
68  in the main .gitlab-ci.yml file.
69
70  Over time we'll get a lot of images pushed to the container registry.
71  The approach we're using allows gitlab project maintainers to
72  remove old images! But it is possible to regenerate the images
73  if you have the need to run a gitlab ci pipeline based on an
74  older branch.
75
76 As a Samba developer/tester, I can setup a Samba env very quickly.
77
78 With Docker:
79
80  cd ~/samba
81  git clean -xdf
82  docker login
83  docker pull registry.gitlab.com/samba-team/devel/samba/samba-ci-ubuntu1804:${sha1sum}
84  docker run -it -v $(pwd):/home/samba/samba samba-ci-ubuntu1804:${sha1sum} bash
85
86 With Vagrant:
87
88  cd bootstrap/generated-dists/
89  vagrant up   # start all
90  vagrant up debian9  # start one
91  vagrant ssh debian9
92  vagrant destroy debian9  # destroy one
93  vagrant destroy  # destroy all
94
95 Or a remote/cloud machine:
96
97  scp bootstrap/generated-dists/fedora30/bootstrap.sh USER@IP:
98  ssh USER@IP
99  sudo bash ./bootstrap.sh
100