forked from lix-project/hydra
203 lines
6.9 KiB
XML
203 lines
6.9 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="chap-installation">
|
|
|
|
<title>Installation</title>
|
|
|
|
<para>
|
|
This chapter explains how to install Hydra on your own build farm server.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Prerequisites</title>
|
|
<para>
|
|
To install and use Hydra you need to have installed the following dependencies:
|
|
|
|
<itemizedlist>
|
|
<listitem>Nix</listitem>
|
|
<listitem>either PostgreSQL or SQLite</listitem>
|
|
<listitem>many Perl packages, notably Catalyst,
|
|
EmailSender, and NixPerl (see the <link
|
|
xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/tools/misc/hydra/default.nix">Hydra
|
|
expression in Nixpkgs</link> for the complete
|
|
list).</listitem>
|
|
</itemizedlist>
|
|
|
|
At the moment, Hydra runs only on GNU/Linux
|
|
(<emphasis>i686-linux</emphasis> and
|
|
<emphasis>x86_64_linux</emphasis>).
|
|
</para>
|
|
|
|
<para>
|
|
For small projects, Hydra can be run on any reasonably
|
|
modern machine. For individual projects you can even run
|
|
Hydra on a laptop. However, the charm of a buildfarm server
|
|
is usually that it operates without disturbing the
|
|
developer's working environment and can serve releases over
|
|
the internet. In conjunction you should typically have your
|
|
source code administered in a version management system,
|
|
such as subversion. Therefore, you will probably want to
|
|
install a server that is connected to the internet. To scale
|
|
up to large and/or many projects, you will need at least a
|
|
considerable amount of diskspace to store builds. Since
|
|
Hydra can schedule multiple simultaneous build jobs, it can
|
|
be useful to have a multi-core machine, and/or attach
|
|
multiple build machines in a network to the central Hydra
|
|
server.
|
|
</para>
|
|
|
|
<para>
|
|
Of course we think it is a good idea to use the <a
|
|
href="http://nixos.org/nixos">NixOS</a> GNU/Linux
|
|
distribution for your buildfarm server. But this is not a
|
|
requirement. The Nix software deployment system can be
|
|
installed on any GNU/Linux distribution in parallel to the
|
|
regular package management system. Thus, you can use Hydra
|
|
on a Debian, Fedora, SuSE, or Ubuntu system.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Getting Nix</title>
|
|
|
|
<para>
|
|
If your server runs NixOS you are all set to continue with
|
|
installation of Hydra. Otherwise you first need to install
|
|
Nix. The latest stable version can be found one <link
|
|
xlink:href="http://nixos.org/nix/download.html">the Nix web
|
|
site</link>, along with a manual, which includes installation
|
|
instructions.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installation</title>
|
|
|
|
<para>
|
|
Hydra can be installed using Nixpkgs:
|
|
|
|
<screen>
|
|
nix-env -Ai hydra -f /path/to/nixpkgs</screen>
|
|
|
|
This makes the tools available in your Nix user environment,
|
|
<literal>$HOME/.nix-profile</literal> by default.
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, the latest development snapshot can be
|
|
installed by visiting the URL
|
|
<link xlink:href="http://hydra.nixos.org/view/hydra/unstable"><literal>http://hydra.nixos.org/view/hydra/unstable</literal></link>
|
|
and use the one-click install available at one of the build pages. You can also
|
|
install Hydra through the channel by performing the following commands:
|
|
|
|
<screen>
|
|
nix-channel --add http://hydra.nixos.org/jobset/hydra/trunk/channel/latest
|
|
nix-channel --update
|
|
nix-env -i hydra</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Command completion should reveal a number of command-line tools from Hydra:
|
|
|
|
<screen>
|
|
hydra_build.pl hydra_eval_jobs hydra_server.pl
|
|
hydra_control.sh hydra_evaluator.pl hydra_update_gc_roots.pl
|
|
hydra_create.pl hydra_queue_runner.pl </screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Creating the database</title>
|
|
<para>
|
|
Hydra stores its results in a database, which can be a
|
|
PostgreSQL or SQLite database. The latter is easier to
|
|
setup, but the former scales better.
|
|
</para>
|
|
|
|
<para>To setup a PostgreSQL
|
|
database with <emphasis>hydra</emphasis> as database name
|
|
and user name, issue the following commands:
|
|
<screen>
|
|
createdb hydra
|
|
echo "CREATE USER hydra WITH PASSWORD '<your-password>' ;" | psql hydra
|
|
cat $prefix/share/hydra/sql/hydra-postgresql.sql | psql hydra
|
|
echo "GRANT ALL ON DATABASE hydra TO hydra;" | psql hydra</screen>
|
|
Note that <emphasis>$prefix</emphasis> is the location of
|
|
Hydra in the nix store.
|
|
</para>
|
|
|
|
<para>
|
|
For SQLite, the following command is all it takes to
|
|
create the database:
|
|
|
|
<screen>
|
|
cat $prefix/share/hydra/sql/hydra-sqlite.sql | sqlite3 /path/to/hydra.sqlite
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To add a user <emphasis>root</emphasis> with <emphasis>admin</emphasis> privileges, execute:
|
|
<screen>
|
|
echo "INSERT INTO Users(userName, emailAddress, password) VALUES ('root', 'some@email.adress.com', '$(echo -n foobar | sha1sum | cut -c1-40)');" | psql hydra
|
|
echo "INSERT INTO UserRoles(userName, role) values('root', 'admin');" | psql hydra
|
|
</screen>
|
|
For SQLite the same commands can be used, with
|
|
<command>psql hydra</command> replaced by
|
|
<command>sqlite3 /path/to/hydra.sqlite</command>.
|
|
</para>
|
|
|
|
<para>
|
|
Hydra uses an environment variable to know which database
|
|
should be used, and a variable which point to a location
|
|
that holds some state. To set these variables for a
|
|
PostgreSQL database, add the following to the
|
|
<filename>.profile</filename> of the user running the
|
|
Hydra services.
|
|
|
|
<screen>
|
|
export HYDRA_DBI="dbi:Pg:dbname=hydra;host=localhost;"
|
|
export HYDRA_DATA=/var/lib/hydra</screen>
|
|
|
|
Make sure that the <emphasis>HYDRA_DATA</emphasis>
|
|
directory exists and is writable for the user which will
|
|
run the Hydra services. For a SQLite database, the
|
|
<varname>HYDRA_DBI</varname> should be set to something
|
|
like <literal>dbi:SQLite:/path/to/hydra.sqlite</literal>
|
|
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Getting started</title>
|
|
<para>
|
|
To start the Hydra webserver, execute:
|
|
<screen>
|
|
hydra_server.pl</screen>
|
|
|
|
When the server is started, you can browse to <ulink>http://localhost:3000/</ulink> to start configuring your Hydra instance.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example: PatchELF</title>
|
|
<para>
|
|
</para>
|
|
|
|
<subsection>
|
|
<title>Defining jobsets</title>
|
|
<para>
|
|
</para>
|
|
</subsection>
|
|
|
|
<subsection>
|
|
<title>Creating views</title>
|
|
<para>
|
|
</para>
|
|
</subsection>
|
|
</section>
|
|
|
|
|
|
|
|
</chapter>
|