From 2e47970a977576106542c3702052a55567e0799f Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Mon, 5 Apr 2021 16:07:00 +0000 Subject: [PATCH] doc: switch shell session code blocks to `console` type. --- doc/manual/src/hacking.md | 46 ++++++++++++++++++++++------------ doc/manual/src/installation.md | 40 ++++++++++++++++++++--------- doc/manual/src/projects.md | 12 ++++++--- 3 files changed, 67 insertions(+), 31 deletions(-) diff --git a/doc/manual/src/hacking.md b/doc/manual/src/hacking.md index c22b7530..98a41a20 100644 --- a/doc/manual/src/hacking.md +++ b/doc/manual/src/hacking.md @@ -3,38 +3,50 @@ 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 enter 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 start a local database, the webserver, and other components with foreman: - $ foreman start +```console +$ foreman start +``` You can run just the Hydra web server in your source tree as follows: - $ ./src/script/hydra-server +```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. @@ -54,4 +66,6 @@ will reload the page every time you save. To build Hydra and its dependencies: - $ nix-build release.nix -A build.x86_64-linux +```console +$ nix-build release.nix -A build.x86_64-linux +``` diff --git a/doc/manual/src/installation.md b/doc/manual/src/installation.md index 94a12041..3fc71fcf 100644 --- a/doc/manual/src/installation.md +++ b/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 +``` +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. diff --git a/doc/manual/src/projects.md b/doc/manual/src/projects.md index c4ea8f55..4228c2dc 100644 --- a/doc/manual/src/projects.md +++ b/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.