<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><para>Nix</para></listitem> <listitem><para>either PostgreSQL or SQLite</para></listitem> <listitem><para>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)</para></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 <link xlink:href="http://nixos.org/nixos">NixOS</link> 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 -f /path/to/nixpkgs -iA hydra</screen> This makes the tools available in your Nix user environment, <literal>$HOME/.nix-profile</literal> by default. </para> --> <para> The latest development snapshot of Hydra 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 using 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 hydra-init hydra-update-gc-roots hydra-eval-jobs hydra-queue-runner hydra-evaluator hydra-server </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 on the PostgreSQL server: <screen> createuser -S -D -R -P hydra createdb -O hydra hydra</screen> Note that <emphasis>$prefix</emphasis> is the location of Hydra in the nix store. </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 file <filename>~/.profile</filename> of the user running the Hydra services. <screen> export HYDRA_DBI="dbi:Pg:dbname=hydra;host=dbserver.example.org;user=hydra;" export HYDRA_DATA=/var/lib/hydra</screen> You can provide the username and password in the file <filename>~/.pgpass</filename>, e.g. <screen> dbserver.example.org:*:hydra:hydra:password</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> <para> Having set these environment variables, you can now initialise the database by doing: <screen> hydra-init</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> </section> <section> <title>Upgrading</title> <para>If you're upgrading Hydra from a previous version, you should do the following to perform any necessary database schema migrations: <screen> hydra-init</screen> </para> </section> <section> <title>Getting Started</title> <para> To start the Hydra web server, execute: <screen> hydra-server</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</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</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</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> <!-- Local Variables: indent-tabs-mode: nil ispell-local-dictionary: "american" End: -->