hydra/doc/manual/installation.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 '&lt;your-password&gt;' ;" | 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 web server, 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>

	<para>
	  The <command>hydra_server.pl</command> command launches the
	  web server.  There are two other processes that come into
	  play:

	  <itemizedlist>
	    <listitem>
	      The <emphasis>evaluator</emphasis> is responsible for
	      peridically evaluating job sets, checking out their
	      dependencies off their version control systems (VCS),
	      and queueing new builds if the result of the evaluation
	      changed.  It is launched by the
	      <command>hydra_evaluator.pl</command> command.
	    </listitem>
	    <listitem>
	      The <emphasis>queue runner</emphasis> launches builds
	      (using Nix) as they are queued by the evaluator,
	      scheduling them onto the configured Nix hosts.  It is
	      launched using the
	      <command>hydra_queue_runner.pl</command> command.
	    </listitem>
	  </itemizedlist>

	  All three processes must be running for Hydra to be fully
	  functional, though it's possible to temporarily stop any one
	  of them for maintenance purposes, for instance.
	</para>
	  
    </section>


</chapter>