Mercurial > bitten > bitten-test

annotate doc/install.txt @ 701:492c18db8f45

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Set the `'Content-Length'` header on master-slave communication. Needed to be http/1.1 compatible. Fixes #475. Thanks pacopablo.
author osimons
date Fri, 16 Oct 2009 16:36:23 +0000
parents 6511c192a957
children 7c8b6a329e12
rev   line source
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
2
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
3 ============
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
4 Installation
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
5 ============
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
6
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
7 .. contents:: Contents
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
8 :depth: 2
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
9 .. sectnum::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
10
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
11
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
12 Prerequisites
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
13 =============
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
14
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
15 Bitten is written in Python, so make sure that you have Python installed.
657
9546e25b9d5c 0.6dev: The install docs did not mention that master requires Trac 0.11.
osimons
parents: 654
diff changeset
16 You'll need Python 2.4 or later for running build slave. The build master is
658
b3237a5ace1d 0.6dev: Linking to Trac in first install paragraph.
osimons
parents: 657
diff changeset
17 a plugin for Trac_ 0.11, and should still work with Python 2.3. Also, make
657
9546e25b9d5c 0.6dev: The install docs did not mention that master requires Trac 0.11.
osimons
parents: 654
diff changeset
18 sure that setuptools_, version 0.6a2 or later, is installed.
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
19
658
b3237a5ace1d 0.6dev: Linking to Trac in first install paragraph.
osimons
parents: 657
diff changeset
20 .. _trac: http://trac.edgewall.org
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
21 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
22
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
23 If that's taken care of, you just need to download and unpack the Bitten
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
24 distribution, and execute the command::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
25
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
26 $ python setup.py install
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
27
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
28 from the top of the directory where you unpacked (or checked out) the Bitten
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
29 code. Note that you may need administrator/root privileges for this step, as
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
30 it will by default attempt to install Bitten to the Python site-packages
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
31 directory on your system.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
32
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
33 It's also a good idea to run the unit tests at this point, to make sure that
522
ad7c5f4b1cf0 Added note that you need Trac for the tests; see #265
dfraser
parents: 436
diff changeset
34 the code works as expected on your platform (please note that Trac_ needs to
ad7c5f4b1cf0 Added note that you need Trac for the tests; see #265
dfraser
parents: 436
diff changeset
35 be installed for the tests to run; see below)::
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
36
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
37 $ python setup.py test
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
38
598
5f3e66e5b451 0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents: 555
diff changeset
39 It is also possible to install only the build slave, installing only the
5f3e66e5b451 0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents: 555
diff changeset
40 parts of Bitten that are needed by clients to run builds::
5f3e66e5b451 0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents: 555
diff changeset
41
682
6511c192a957 0.6dev: Complete rework of the slave-only install to use `setuptools.Feature` to disable the master-parts. This should make all regular distribution commands like 'test', 'sdist', 'bdist_egg' and so on work as intended, and the output can be adjusted using option `--without-master` (master is enabled by default).
osimons
parents: 658
diff changeset
42 $ python setup.py --without-master install
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
43
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
44 What's left to do now depends on whether you want to use the build master and
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
45 web interface, or just the build slave. In the latter case, you're already
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
46 done. You might need to install software that the build of your project
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
47 requires, but the Bitten build slave itself doesn't require anything extra.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
48
523
a89925df9d88 We now require Trac 0.11
dfraser
parents: 522
diff changeset
49 For the build master and web interface, you'll need to install Trac_ 0.11 or
555
fe4293ddf51c Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents: 523
diff changeset
50 later. Please refer to the Trac documentation for information on how it is installed.
436
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
51
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
52
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
53 Build Master Configuration
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
54 ==========================
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
55
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
56 Once both Bitten and Trac are installed and working, you'll have to introduce
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
57 Bitten to your Trac project environment. If you don't have a Trac project
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
58 set up yet, you'll need to do so in order to use Bitten.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
59
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
60 If you already have a Trac project environment, the Bitten plugin needs to be
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
61 explicitly enabled in the Trac configuration. This is done by adding it to the
436
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
62 ``[components]`` section in ``/path/to/projenv/conf/trac.ini``:
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
63
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
64 .. code-block:: ini
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
65
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
66 [components]
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
67 bitten.* = enabled
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
68
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
69 The Trac web interface should now inform you with an error message that the
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
70 environment needs to be upgraded. To do this, run::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
71
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
72 $ trac-admin /path/to/projenv upgrade
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
73
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
74 This will create the database tables and directories that Bitten requires.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
75 You probably also want to grant permissions to someone (such as yourself)
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
76 to manage build configurations, and allow anonymous users to view the
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
77 status and results of builds::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
78
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
79 $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
80 $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
81 $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
82
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
83 You should now see an additional tab labeled "Build Status" in the Trac
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
84 navigation bar. This link will take you to the list of build configurations,
436
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
85 which at this point is of course empty.
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
86
555
fe4293ddf51c Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents: 523
diff changeset
87 If Bitten is installed, and you are logged in as a user with the required
fe4293ddf51c Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents: 523
diff changeset
88 permissions, you should see additional administration pages inside the “Admin”
fe4293ddf51c Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents: 523
diff changeset
89 area, under a group named “Builds”. These pages allow you to set options of the
fe4293ddf51c Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents: 523
diff changeset
90 build master, and manage build configurations.
436
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
91
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
92 Add a new build configuration and fill out the form. Also, add at least one
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
93 target platform after saving the configuration. Last but not least, you'll have
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
94 to "activate" your new build configuration.
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
95
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
96
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
97 Running the Build Slave
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
98 =======================
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
99
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
100 The build slave can be run on any machine that can connect to the machine
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
101 on which the build master is running. The installation of Bitten should have put
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
102 a `bitten-slave` executable on your path. If the script is not on your path,
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
103 look for it in the `bin` or `scripts` subdirectory of your Python installation.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
104
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
105 To get a list of options for the build slave, execute it with the `--help`
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
106 option::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
107
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
108 $ bitten-slave --help
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
109
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
110 To run the build slave against a Bitten-enabled Trac site installed at
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
111 http://myproject.example.org/trac, you'd run::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
112
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
113 $ bitten-slave http://myproject.example.org/trac/builds
Copyright (C) 2012-2017 Edgewall Software