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><para>Nix</para></listitem>
        <listitem><para>PostgreSQL</para></listitem>
        <listitem><para>many Perl packages, notably Catalyst, EmailSender,
        and NixPerl (see the <link
        xlink:href="https://github.com/NixOS/hydra/blob/master/release.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/master/channel/latest
nix-channel --update
nix-env -i hydra</screen>
    </para>

    <para>
      Command completion should reveal a number of command-line tools
      from Hydra, such as <command>hydra-queue-runner</command>.
    </para>
  </section>

  <section>
    <title>Creating the database</title>
    <para>
      Hydra stores its results in a PostgreSQL database.
    </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.
    </para>

    <para>
      Having set these environment variables, you can now initialise
      the database by doing:
      <screen>
hydra-init</screen>
    </para>

    <para>
      To create projects, you need to create a user with
      <emphasis>admin</emphasis> privileges.  This can be done using
      the command <command>hydra-create-user</command>:

<screen>
$ hydra-create-user alice --full-name 'Alice Q. User' \
    --email-address 'alice@example.org' --password foobar --role admin
</screen>

      Additional users can be created through the web interface.
    </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
          periodically 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>

  <section>
    <title> Serving behind reverse proxy </title>

    <para>
      To serve hydra web server behind reverse proxy like
      <emphasis>nginx</emphasis> or <emphasis>httpd</emphasis> some
      additional configuration must be made.
    </para>

    <para>
      Edit your <literal>hydra.conf</literal> file in a similar way to
      this example:

      <screen>
using_frontend_proxy 1
base_uri example.com</screen>

      <literal>base_uri</literal> should be your hydra servers proxied URL.

      If you are using Hydra nixos module then setting <literal>hydraURL</literal>
      option should be enough.

    </para>

    <para>

      If you want to serve Hydra with a prefix path, for example
      <ulink>http://example.com/hydra</ulink> then you need to configure your
      reverse proxy to pass <literal>X-Request-Base</literal> to hydra, with
      prefix path as value.

      For example if you are using nginx, then use configuration similar to following:
      <screen>
server {
    listen 433 ssl;
    server_name example.com;
    .. other configuration ..
    location /hydra/ {

        proxy_pass     http://127.0.0.1:3000;
        proxy_redirect http://127.0.0.1:3000 https://example.com/hydra;

        proxy_set_header  Host              $host;
        proxy_set_header  X-Real-IP         $remote_addr;
        proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header  X-Forwarded-Proto $scheme;
        proxy_set_header  X-Request-Base    /hydra;
    }
}</screen>

    </para>
  </section>
  <section>
    <title>Using LDAP as authentication backend (optional)</title>
    <para>
      Instead of using Hydra's built-in user management you can optionally use LDAP to manage roles and users.
    </para>

    <para>
      The <command>hydra-server</command> accepts the environment
      variable <emphasis>HYDRA_LDAP_CONFIG</emphasis>. The value of
      the variable should point to a valid YAML file containing the
      Catalyst LDAP configuration. The format of the configuration
      file is describe in the
      <link xlink:href="https://metacpan.org/pod/Catalyst::Authentication::Store::LDAP#CONFIGURATION-OPTIONS">
        <emphasis>Catalyst::Authentication::Store::LDAP</emphasis> documentation</link>.
      An example is given below.
    </para>

    <para>
      Roles can be assigned to users based on their LDAP group membership
      (<emphasis>use_roles: 1</emphasis> in the below example).
      For a user to have the role <emphasis>admin</emphasis> assigned to them
      they should be in the group <emphasis>hydra_admin</emphasis>. In general
      any LDAP group of the form <emphasis>hydra_some_role</emphasis>
      (notice the <emphasis>hydra_</emphasis> prefix) will work.
    </para>

    <screen>
credential:
  class: Password
  password_field: password
  password_type: self_check
store:
  class: LDAP
  ldap_server: localhost
  ldap_server_options.timeout: 30
  binddn: "cn=root,dc=example"
  bindpw: notapassword
  start_tls: 0
  start_tls_options
    verify:  none
  user_basedn: "ou=users,dc=example"
  user_filter: "(&amp;(objectClass=inetOrgPerson)(cn=%s))"
  user_scope: one
  user_field: cn
  user_search_options:
    deref: always
  use_roles: 1
  role_basedn: "ou=groups,dc=example"
  role_filter: "(&amp;(objectClass=groupOfNames)(member=%s))"
  role_scope: one
  role_field: cn
  role_value: dn
  role_search_options:
    deref: always
    </screen>
  </section>
</chapter>

<!--
 Local Variables:
 indent-tabs-mode: nil
 ispell-local-dictionary: "american"
 End:
 -->