release as 0.57
[piuparts/piuparts.git] / README_pejacevic.txt
1 Notes about the piuparts installation on pejacevic.debian.org and it's slave
2 ============================================================================
3
4 This document describes the setup for http://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 two systems: pejacevic.debian.org,
14 running the piuparts-master instance and an apache webserver to display the
15 results and piu-slave-bm-a.debian.org, running four piuparts-slave nodes.
16
17 === piuparts installation from source
18
19 * basically, apt-get build-dep piuparts - in reality both systems get their
20   package configuration from git.debian.org/git/mirror/debian.org.git
21 * pejacevic runs a webserver as well (see below for apache configuration)
22 * Copy 'http://anonscm.debian.org/gitweb/?p=piuparts/piuparts.git;hb=master;a=blob_plain;f=update-piuparts-master-setup'
23   and 'http://anonscm.debian.org/gitweb/?p=piuparts/piuparts.git;hb=master;a=blob_plain;f=update-piuparts-slave-setup'
24   to the hosts which should be master and slave. (It's possible and has been
25   done for a long time to run them on the same host.(
26   Run the scripts as the piupartsm and piupartss users and clone that git
27   repositry into '/srv/piuparts.debian.org/src' in the first place. Then
28   checkout the bikeshed branch.
29 *  See below for further user setup instructions.
30 * Provide '/srv/piuparts.debian.org' - on the slave ideally with a 'tmp'
31   directory which is on tmpfs.
32 * `sudo ln -s /srv/piuparts.debian.org/etc/piuparts /etc/piuparts`
33
34 === User setup
35
36 On pejacevic the piuparts-master user piupartsm needs to be installed, on
37 piu-slave-bm-a a piupartss user is needed for the slave.
38 Both are members of the group piuparts and '/srv/piuparts.debian.org' needs to
39 be chmod 2775 and chown piuparts(sm):piuparts.
40
41 ==== '~/bashrc' for piupartsm and piupartss
42
43 Do this for the piupartsm user on pejacevic and piupartss on the slave:
44
45 ----
46 piupartsm@pejacevic$ cat >> ~/.bashrc <<-EOF
47
48 # added manually for piuparts
49 umask 0002
50 export PATH="~/bin:\$PATH"
51 EOF
52 ----
53
54 ==== set up ssh pubkey authentification
55
56 Then create an SSH keypair for piupartss and put it into
57 '/etc/ssh/userkeys/piupartsm' on pejacevic, so the piupartss user can login
58 with ssh and run only piuparts-master. Restrict it like this:
59
60 ----
61 $ cat /etc/ssh/userkeys/piupartsm
62 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 ...
63 ----
64
65 === Setup sudo
66
67 This is actually done by DSA:
68
69 ==== '/etc/sudoers' for pejacevic
70
71 ----
72 #piuparts admins
73 %piuparts       ALL=(piupartsm) ALL
74 ----
75
76 ==== '/etc/sudoers' for piu-slave-bm-a
77
78 ----
79 # The piuparts slave needs to handle chroots.
80 piupartss       ALL = NOPASSWD: ALL
81
82 #piuparts admins
83 %piuparts       ALL=(piupartss) ALL
84 ----
85
86 === Apache configuration
87
88 Any other webserver will do but apache is used on pejacevic (and maintained by DSA):
89
90 ----
91 <VirtualHost *:80>
92         ServerName piuparts.debian.org
93
94         ServerAdmin debian-admin@debian.org
95
96         ErrorLog /var/log/apache2/piuparts.debian.org-error.log
97         CustomLog /var/log/apache2/piuparts.debian.org-access.log combined
98
99         DocumentRoot /srv/piuparts.debian.org/htdocs
100         AddType text/plain log
101
102         HostnameLookups Off
103         UseCanonicalName Off
104         ServerSignature On
105         <IfModule mod_userdir.c>
106                 UserDir disabled
107         </IfModule>
108 </VirtualHost>
109 # vim:set syn=apache:
110 ----
111
112 == Running piuparts
113
114 === Updating the piuparts installation
115
116 Updating the master, pejacevic.debian.org:
117
118 ----
119 holger@pejacevic$ sudo su - piupartsm update-piuparts-master-setup bikeshed origin
120 ----
121
122 Updating the slave, piu-slave-bm-a.debian.org:
123
124 ----
125 holger@piu-slave-bm-a$ sudo su - piupartss update-piuparts-slave-setup bikeshed origin
126 ----
127
128 === Running piuparts
129
130 ==== Starting and stopping the slaves
131
132 Run the following script under *your* user account to start four instances of
133 piuparts-slave on pejacevic, piuparts-master will be started automatically by
134 the slaves.
135
136 ----
137 holger@pejacevic:~$ sudo -u piupartss -i slave_run
138 ----
139
140 There are several cronjobs installed via '~piupartsm/crontab' and
141 '~piupartss/crontab') which monitor the slaves and the hosts it's 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 === Filing bugs
162
163 Use the following usertags:
164
165 ----
166 User: debian-qa@lists.debian.org
167 Usertags: piuparts piuparts.d.o
168 ----
169
170 === Generating reports for the website
171
172 'piuparts-report' is run daily at midnight and at noon from
173 '~piupartsm/crontab' on pejacevic.
174
175 === Cronjobs to aid problem spotting
176
177 Some cronjobs to aid problem spotting reside in '~piupartsm/bin/' and are run
178 daily by '~piupartsm/crontab'.
179
180 - 'detect_network_issues' should detect failed piuparts runs due to network
181   issues on the host.
182 - 'detect_stale_mounts' should detect stale mountpoints (usually of /proc)
183   from failed piuparts runs.
184
185 More checks should be added as we become aware of them.
186
187
188 == Authors
189
190 Last updated: May 2013
191
192 Holger Levsen <holger@layer-acht.org>
193
194 // vim: set filetype=asciidoc: