forked from lix-project/hydra
339 lines
11 KiB
XML
339 lines
11 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><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: "(&(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: "(&(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:
|
|
-->
|