Merge branch 'master' of git://gitorious.org/opensuse/build-service
[opensuse:build-service.git] / INSTALL
1 ===========================
2 Installation and Deployment
3 ===========================
4
5 This document explains how to setup the Build Service for development or
6 deployment.
7
8
9 Prerequisites
10 =============
11
12 Before you can start developing for the openSUSE Build Service or deploying
13 it, you have to fetch some additional dependencies in the repository. Please
14 issue the following commands in your shell:
15
16  $ git submodule init
17  $ git submodule update
18  $ git pull origin master
19
20
21 Software dependencies
22 =====================
23
24 The various parts of the openSUSE Build Service are implemented in different
25 languages. Therefore it has quite some additional dependencies. Also, it allows
26 to configure the database backend (e.g. you can even use SQLite3 for
27 development / testing and MySQL for production).
28
29 - Perl version 5.12.1 or later
30 - MySQL version 5.1.46 or later and / or SQLite3 version 3.6.23 or later
31 - Ruby version 1.8.7 and Ruby on Rails version 2.3.8 (exact versions)
32
33 To get all the dependencies and useful additional tools for openSUSE-11.3,
34 please issue the following commands as root user in your shell:
35
36  $ zypper addrepo --name "openSUSE-11.3 Tool" \
37     http://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_11.3/ \
38     opensuse-tools
39  $ zypper refresh
40  $ zypper install devel_rpm_build osc mysql-community-server sqlite3 \
41                   perl perl-Net-Domain perl-Net-SSLeay perl-BSSolv \
42                   ruby ruby-mysql rubygems rubygem-sqlite3 rubygem-rails-2_3 \
43                   rubygem-delayed_job rubygem-gruff rubygem-libxml-ruby \
44                   rubygem-sqlite3 rubygem-daemons \
45                   rubygem-exception_notification
46
47
48 Deployment with RPM packages
49 ============================
50
51 Please have a look at the following file on how to set up a complete Build
52 Service instance from RPM packages: dist/README.SETUP
53
54
55 Deployment by hand
56 ==================
57
58 The Build Service is flexible enough to support several deployment scenarios.
59 These scenarios are described in the following (with increasing complexity).
60
61
62 Option 1: Only use the webui
63 ----------------------------
64
65 If you want to work only on the Rails web frontend (webui) or running your own
66 webui instance, there is no need to have an own backend server running. It is
67 sufficient to start the webui with its default values. For that to work you
68 have to change into its subdirectory and create the initial config like this:
69
70  $ cd src/webui
71  $ cp config/database.yml.example config/database.yml
72
73 Afterwards you can simply start the webui like this:
74
75  $ ./scripts/server
76
77 Open up your favorite browser and enter the address http://127.0.0.1:3000/
78 and you should see your own Build Service webui instance. Thats it, actually.
79
80 To speed things up a bit, you can install a local memory cache like this (as
81 root in a terminal):
82
83  $ zypper in memcached
84  $ rcmemcached start
85  $ insserv memcached
86
87 You can also use Capistrano to deploy the web interface on production machines:
88
89  $ cap deploy:update        - Updates the sources on the server and changes the
90                               current symlink
91  $ cap deploy:migrate       - Runs database migrations
92  $ cap deploy               - Updates and restarts the server
93  $ cap deploy:pending       - or
94  $ cap deploy:pending:diff  - will show upcoming changes
95  $ cap deploy:rollback      - To get back to the previous version:
96
97 Additional information on how to set up your local development instance and how
98 to contribute can be found in the openSUSE wiki:
99
100     http://en.opensuse.org/openSUSE:Build_Service_Installation_Tutorial
101
102
103 Option 2: Setup a complete Build Service
104 ----------------------------------------
105
106 In addition to the steps described above, please refer to the file
107 src/backend/README. Afterwards, you have to configure your webui instance to
108 use your local api instance. Have a look at the documentation in the respective
109 files under src/webui/config/environments.