Mercurial > bitten > bitten-test

annotate doc/install.txt @ 448:ccddf91740d1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix deletion of obsolete builds in build queue.
author cmlenz
date Thu, 23 Aug 2007 18:37:42 +0000
parents cfbc9ee622d5
children ad7c5f4b1cf0
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.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
16 You'll need Python 2.3 or later. Also, make sure that setuptools_, version 0.6a2
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
17 or later, is installed.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
18
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
19 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
20
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
21 If that's taken care of, you just need to download and unpack the Bitten
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
22 distribution, and execute the command::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
23
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
24 $ python setup.py install
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
25
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
26 from the top of the directory where you unpacked (or checked out) the Bitten
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
27 code. Note that you may need administrator/root privileges for this step, as
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
28 it will by default attempt to install Bitten to the Python site-packages
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
29 directory on your system.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
30
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
31 It's also a good idea to run the unit tests at this point, to make sure that
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
32 the code works as expected on your platform::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
33
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
34 $ python setup.py test
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
35
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
36
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
37 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
38 web interface, or just the build slave. In the latter case, you're already
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
39 done. You might need to install software that the build of your project
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
40 requires, but the Bitten build slave itself doesn't require anything extra.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
41
436
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
42 For the build master and web interface, you'll need to install Trac_ 0.10 or
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
43 later and the TracWebAdmin_ plugin. Please refer to the Trac documentation for
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
44 information on how it is installed.
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
45
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
46 .. _trac: http://trac.edgewall.org/
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
47 .. _tracwebadmin: http://trac.edgewall.org/wiki/WebAdmin
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
48
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
49
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
50 Build Master Configuration
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
51 ==========================
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
52
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
53 Once both Bitten and Trac are installed and working, you'll have to introduce
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
54 Bitten to your Trac project environment. If you don't have a Trac project
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
55 set up yet, you'll need to do so in order to use Bitten.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
56
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
57 If you already have a Trac project environment, the Bitten plugin needs to be
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
58 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
59 ``[components]`` section in ``/path/to/projenv/conf/trac.ini``:
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
60
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
61 .. code-block:: ini
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
62
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
63 [components]
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
64 bitten.* = enabled
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
65
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
66 The Trac web interface should now inform you with an error message that the
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
67 environment needs to be upgraded. To do this, run::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
68
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
69 $ trac-admin /path/to/projenv upgrade
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
70
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
71 This will create the database tables and directories that Bitten requires.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
72 You probably also want to grant permissions to someone (such as yourself)
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
73 to manage build configurations, and allow anonymous users to view the
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
74 status and results of builds::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
75
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
76 $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
77 $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
78 $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
79
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
80 You should now see an additional tab labeled "Build Status" in the Trac
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
81 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
82 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
83
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
84 To add build configurations, you need to have the TracWebAdmin_ plugin
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
85 installed.
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
86
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
87 .. warning:: The TracWebAdmin needs to be installed even if you're using Trac
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
88 0.11 or later, which basically provides a builtin web
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
89 administration interface. Make sure that you disable the plugin in
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
90 that case, though (``webadmin.* = disabled``). While somewhat
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
91 counterintuitive, this process allows the Bitten administration UI
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
92 to neatly integrate into the new web administration interface added
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
93 in Trac 0.11.
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
94
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
95 If both TracWebAdmin_ and Bitten are installed, and you are logged in as a user
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
96 with the required permissions, you should see additional administration pages
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
97 inside the “Admin” area, under a group named “Builds”. These pages allow you to
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
98 set options of the build master, and manage build configurations.
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
99
cfbc9ee622d5 Finish the move of build configuration management into the admin interface.
cmlenz
parents: 412
diff changeset
100 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
101 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
102 to "activate" your new build configuration.
412
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
103
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
104
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
105 Running the Build Slave
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
106 =======================
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
107
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
108 The build slave can be run on any machine that can connect to the machine
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
109 on which the build master is running. The installation of Bitten should have put
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
110 a `bitten-slave` executable on your path. If the script is not on your path,
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
111 look for it in the `bin` or `scripts` subdirectory of your Python installation.
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
112
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
113 To get a list of options for the build slave, execute it with the `--help`
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
114 option::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
115
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
116 $ bitten-slave --help
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
117
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
118 To run the build slave against a Bitten-enabled Trac site installed at
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
119 http://myproject.example.org/trac, you'd run::
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
120
84b8cde2dfd4 Start with documentation.
cmlenz
parents:
diff changeset
121 $ bitten-slave http://myproject.example.org/trac/builds
Copyright (C) 2012-2017 Edgewall Software