Merge pull request #908 from grahamc/manual-hacking

Manual: mention in hacking docs

Procfile

@@ -1,5 +1,6 @@
-hydra-server: ./foreman/start-hydra.sh
-hydra-queue-runner: ./foreman/start-queue-runner.sh
 hydra-evaluator: ./foreman/start-evaluator.sh
+hydra-queue-runner: ./foreman/start-queue-runner.sh
 hydra-notify: ./foreman/start-notify.sh
+hydra-server: ./foreman/start-hydra.sh
+manual: ./foreman/start-manual.sh
 postgres: ./foreman/start-postgres.sh

doc/manual/src/hacking.md

@@ -1,41 +1,52 @@
-Hacking
-=======
+# Hacking
 
 This section provides some notes on how to hack on Hydra. To get the
 latest version of Hydra from GitHub:
 
-    $ git clone git://github.com/NixOS/hydra.git
-    $ cd hydra
+```console 
+$ git clone git://github.com/NixOS/hydra.git
+$ cd hydra
+```
 
-To build it and its dependencies:
+To enter a shell in which all environment variables (such as `PERL5LIB`)
+and dependencies can be found:
 
-    $ nix-build release.nix -A build.x86_64-linux
-
-To build all dependencies and start a shell in which all environment
-variables (such as PERL5LIB) are set up so that those dependencies can
-be found:
-
-    $ nix-shell
+```console
+$ nix-shell
+```
 
 To build Hydra, you should then do:
 
-    [nix-shell]$ ./bootstrap
-    [nix-shell]$ configurePhase
-    [nix-shell]$ make
+```console
+[nix-shell]$ ./bootstrap
+[nix-shell]$ configurePhase
+[nix-shell]$ make
+```
 
-You can run the Hydra web server in your source tree as follows:
+You start a local database, the webserver, and other components with
+foreman:
 
-    $ ./src/script/hydra-server
+```console
+$ foreman start
+```
+
+You can run just the Hydra web server in your source tree as follows:
+
+```console
+$ ./src/script/hydra-server
+```
 
 You can run Hydra's test suite with the following:
 
-    [nix-shell]$ make check
-    [nix-shell]$ # to run as many tests as you have cores:
-    [nix-shell]$ make check YATH_JOB_COUNT=$NIX_BUILD_CORES
-    [nix-shell]$ # or run yath directly:
-    [nix-shell]$ yath test
-    [nix-shell]$ # to run as many tests as you have cores:
-    [nix-shell]$ yath test -j $NIX_BUILD_CORES
+```console
+[nix-shell]$ make check
+[nix-shell]$ # to run as many tests as you have cores:
+[nix-shell]$ make check YATH_JOB_COUNT=$NIX_BUILD_CORES
+[nix-shell]$ # or run yath directly:
+[nix-shell]$ yath test
+[nix-shell]$ # to run as many tests as you have cores:
+[nix-shell]$ yath test -j $NIX_BUILD_CORES
+```
 
 When using `yath` instead of `make check`, ensure you have run `make`
 in the root of the repository at least once.
@@ -44,3 +55,17 @@ in the root of the repository at least once.
 if run with high parallelism [due to an issue in
 `Test::PostgreSQL`](https://github.com/TJC/Test-postgresql/issues/40)
 causing database ports to collide.
+
+## Working on the Manual
+
+By default, `foreman start` runs mdbook in "watch" mode. mdbook listens
+at [http://localhost:63332/](http://localhost:63332/), and
+will reload the page every time you save.
+
+## Building
+
+To build Hydra and its dependencies:
+
+```console
+$ nix-build release.nix -A build.x86_64-linux
+```

doc/manual/src/installation.md

@@ -76,8 +76,10 @@ Hydra stores its results in a PostgreSQL database.
 To setup a PostgreSQL database with *hydra* as database name and user
 name, issue the following commands on the PostgreSQL server:
 
-    createuser -S -D -R -P hydra
-    createdb -O hydra hydra
+```console
+createuser -S -D -R -P hydra
+createdb -O hydra hydra
+```
 
 Note that *\$prefix* is the location of Hydra in the nix store.
 
@@ -86,12 +88,16 @@ 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 `~/.profile` of the user running the Hydra services.
 
-    export HYDRA_DBI="dbi:Pg:dbname=hydra;host=dbserver.example.org;user=hydra;"
-    export HYDRA_DATA=/var/lib/hydra
+```console
+export HYDRA_DBI="dbi:Pg:dbname=hydra;host=dbserver.example.org;user=hydra;"
+export HYDRA_DATA=/var/lib/hydra
+```
 
 You can provide the username and password in the file `~/.pgpass`, e.g.
 
-    dbserver.example.org:*:hydra:hydra:password
+```
+dbserver.example.org:*:hydra:hydra:password
+```
 
 Make sure that the *HYDRA\_DATA* directory exists and is writable for
 the user which will run the Hydra services.
@@ -99,13 +105,17 @@ the user which will run the Hydra services.
 Having set these environment variables, you can now initialise the
 database by doing:
 
-    hydra-init
+```console
+hydra-init
+```
 
 To create projects, you need to create a user with *admin* privileges.
 This can be done using the command `hydra-create-user`:
 
-    $ hydra-create-user alice --full-name 'Alice Q. User' \
-        --email-address 'alice@example.org' --password foobar --role admin
+```console
+$ hydra-create-user alice --full-name 'Alice Q. User' \
+    --email-address 'alice@example.org' --password foobar --role admin
+```
 
 Additional users can be created through the web interface.
 
@@ -115,14 +125,18 @@ Upgrading
 If you\'re upgrading Hydra from a previous version, you should do the
 following to perform any necessary database schema migrations:
 
-    hydra-init
+```console
+hydra-init
+```
 
 Getting Started
 ---------------
 
 To start the Hydra web server, execute:
 
-    hydra-server
+```console
+hydra-server
+```
 
 When the server is started, you can browse to [http://localhost:3000/]()
 to start configuring your Hydra instance.
@@ -158,8 +172,10 @@ some additional configuration must be made.
 
 Edit your `hydra.conf` file in a similar way to this example:
 
-    using_frontend_proxy 1
-    base_uri example.com
+```conf
+using_frontend_proxy 1
+base_uri example.com
+```
 
 `base_uri` should be your hydra servers proxied URL. If you are using
 Hydra nixos module then setting `hydraURL` option should be enough.
@@ -246,4 +262,3 @@ general any LDAP group of the form *hydra\_some\_role* (notice the
       role_value: dn
       role_search_options:
         deref: always
-

doc/manual/src/projects.md

@@ -220,7 +220,9 @@ expressions, they can be evaluated using the standard Nix tools.
 To evaluate the `tarball` jobset of the above example, just
 run:
 
-    $ nix-build release.nix -A tarball
+```console
+$ nix-build release.nix -A tarball
+```
 
 However, doing this with the example as is will probably
 yield an error like this:
@@ -230,11 +232,15 @@ yield an error like this:
 The error is self-explanatory. Assuming `$HOME/src/hello` points to a
 checkout of Hello, this can be fixed this way:
 
-    $ nix-build -I ~/src release.nix -A tarball
+```console
+$ nix-build -I ~/src release.nix -A tarball
+```
 
 Similarly, the `build` jobset can be evaluated:
 
-    $ nix-build -I ~/src release.nix -A build
+```console
+$ nix-build -I ~/src release.nix -A build
+```
 
 The `build` job reuses the result of the `tarball` job, rebuilding it
 only if it needs to.

foreman/start-hydra.sh

@@ -5,6 +5,12 @@ while ! pg_isready -h $(pwd)/.hydra-data/postgres -p 64444; do sleep 1; done
 
 createdb -h $(pwd)/.hydra-data/postgres -p 64444 hydra
 
+# create a db for the default user. Not sure why, but
+# the terminal is otherwise spammed with:
+#
+#     FATAL:  database "USERNAME" does not exist
+createdb -h $(pwd)/.hydra-data/postgres -p 64444 "$(whoami)" || true
+
 hydra-init
 hydra-create-user alice --password foobar --role admin
 

foreman/start-manual.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+mdbook serve \
+  --port 63332 \
+  --dest-dir ./.hydra-data/manual \
+  ./doc/manual/