release 0.61
[piuparts/piuparts.git] / README_pejacevic.txt
1 Notes about the piuparts installation on pejacevic.debian.org and it's slave(s)
2 ===============================================================================
3
4 This document describes the setup for https://piuparts.debian.org - it's used
5 for reference for the Debian System Administrators (DSA) as well as a guide
6 for other setting up a similar system, with the piuparts source code
7 installed from git. For regular installations we recommend to use the
8 piuparts-master and piuparts-slaves packages as described in
9 /usr/share/doc/piuparts-master/README_server.txt
10
11 == Installation
12
13 piuparts.debian.org is a setup running on several systems:
14 pejacevic.debian.org, running the piuparts-master instance and an apache
15 webserver to display the results and piu-slave-bm-a.debian.org, running
16 four piuparts-slave nodes. Not yet in operation there is another,
17 piu-slave-1und1-01.debian.org, which soon shall go into operation...
18
19 === piuparts installation from source
20
21 * basically, apt-get build-dep piuparts - in reality both systems get their
22   package configuration from git.debian.org/git/mirror/debian.org.git
23 * pejacevic runs a webserver as well (see below for apache configuration)
24 * Copy 'https://anonscm.debian.org/cgit/piuparts/piuparts.git/tree/update-piuparts-master-setup?h=develop'
25   and 'https://anonscm.debian.org/cgit/piuparts/piuparts.git/tree/update-piuparts-slave-setup?h=develop'
26   to the hosts which should be master and slave. (It's possible and has been
27   done for a long time to run them on the same host.(
28   Run the scripts as the piupartsm and piupartss users and clone that git
29   repository into '/srv/piuparts.debian.org/src' in the first place. Then
30   checkout the develop branch.
31 * Ideally provide '/srv/piuparts.debian.org/tmp' on (a sufficiently large)
32   tmpfs.
33 * `sudo ln -s /srv/piuparts.debian.org/etc/piuparts /etc/piuparts`
34 * See below for further user setup instructions.
35
36 === User setup
37
38 On pejacevic the piuparts-master user piupartsm needs to be created, on
39 piu-slave-bm-a a piupartss user is needed for the slave.
40 Both are members of the group piuparts and '/srv/piuparts.debian.org' needs to
41 be chmod 2775 and chown piuparts(sm):piuparts.
42
43 ==== '~/bashrc' for piupartsm and piupartss
44
45 Do this for the piupartsm user on pejacevic and piupartss on the slave(s):
46
47 ----
48 piupartsm@pejacevic$ cat >> ~/.bashrc <<-EOF
49
50 # added manually for piuparts
51 umask 0002
52 export PATH="~/bin:\$PATH"
53 EOF
54 ----
55
56 ==== set up ssh pubkey authentification
57
58 Then create an SSH keypair for piupartss and put it into
59 '/etc/ssh/userkeys/piupartsm' on pejacevic, so the piupartss user can login
60 with ssh and run only piuparts-master. Restrict it like this:
61
62 ----
63 $ cat /etc/ssh/userkeys/piupartsm
64 command="/srv/piuparts.debian.org/share/piuparts/piuparts-master",from="2001:41c8:1000:21::21:7,5.153.231.7",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa ...
65 ----
66
67 === Setup sudo for the slave(s)
68
69 This is actually done by DSA:
70
71 ==== '/etc/sudoers' for piu-slave-bm-a and piu-slave-1und1-01
72
73 ----
74 # The piuparts slave needs to handle chroots.
75 piupartss       ALL = NOPASSWD: /usr/sbin/piuparts *, \
76                                 /bin/umount /srv/piuparts.debian.org/tmp/tmp*, \
77                                 /usr/bin/test -f /srv/piuparts.debian.org/tmp/tmp*, \
78                                 /usr/bin/rm -rf --one-file-system /srv/piuparts.debian.org/tmp/tmp*
79 ----
80
81 === Apache configuration
82
83 Any other webserver will do but apache is used on pejacevic (and maintained by DSA):
84
85 ----
86 <VirtualHost *:80>
87         ServerName piuparts.debian.org
88
89         ServerAdmin debian-admin@debian.org
90
91         ErrorLog /var/log/apache2/piuparts.debian.org-error.log
92         CustomLog /var/log/apache2/piuparts.debian.org-access.log combined
93
94         DocumentRoot /srv/piuparts.debian.org/htdocs
95         AddType text/plain .log
96         AddDefaultCharset utf-8
97
98         HostnameLookups Off
99         UseCanonicalName Off
100         ServerSignature On
101         <IfModule mod_userdir.c>
102                 UserDir disabled
103         </IfModule>
104 </VirtualHost>
105 # vim:set syn=apache:
106 ----
107
108 == Running piuparts
109
110 === Updating the piuparts installation
111
112 Updating the master, pejacevic.debian.org:
113
114 ----
115 holger@pejacevic~$ sudo su - piupartsm update-piuparts-master-setup develop origin
116 ----
117
118 Updating the slave(s), for example on piu-slave-bm-a.debian.org:
119
120 ----
121 holger@piu-slave-bm-a~$ sudo su - piupartss update-piuparts-slave-setup develop origin
122 ----
123
124 === Running piuparts
125
126 When running piuparts in master/slave mode, the master is never run by itself,
127 instead it is always started by the slave(s).
128
129 ==== Starting and stopping the slaves
130
131 Run the following script under *your* user account to start four instances of
132 piuparts-slave on pejacevic, piuparts-master will be started automatically by
133 the slaves.
134
135 ----
136 holger@piu-slave-bm-a:~$ sudo -u piupartss -i slave_run
137 ----
138
139 There are several cronjobs installed via '~piupartsm/crontab' and
140 '~piupartss/crontab') to monitor both master and slave as well as the hosts
141 they are running on.
142
143 It's possible to kill a slave any time by pressing Ctrl-C.
144 Pressing Ctrl-C once will wait for the current test to finish,
145 pressing twice will abort the currently running test (which will be redone).
146 Clean termination may take some time and can be aborted by a third Ctrl-C,
147 but that may leave temporary directories and processes around.
148
149 See the 'piuparts_slave_run (8)' manpage for more information on 'slave_run'.
150
151 ==== Joining an existing slave session
152
153 Run the following script under *your* user account:
154
155 ----
156 holger@pejacevic:~$ sudo -u piupartss -i slave_join
157 ----
158
159 See the 'piuparts_slave_join (8)' manpage for more information on 'slave_join'.
160
161 === Generating reports for the website
162
163 'piuparts-report' is run daily at midnight and at noon from
164 '~piupartsm/crontab' on pejacevic.
165
166 === Cronjobs to aid problem spotting
167
168 Some cronjobs to aid problem spotting reside in '~piupartsm/bin/' and are run
169 daily by '~piupartsm/crontab'.
170
171 - 'detect_network_issues' should detect failed piuparts runs due to network
172   issues on the host.
173 - 'detect_stale_mounts' should detect stale mountpoints (usually of /proc)
174   from failed piuparts runs.
175
176 More checks should be added as we become aware of them.
177
178
179 == Authors
180
181 Last updated: October 2014
182
183 Holger Levsen <holger@layer-acht.org>
184
185 // vim: set filetype=asciidoc: