doc: switch shell session code blocks to console type.

This commit is contained in:
Graham Christensen 2021-04-05 16:07:00 +00:00
parent 16902f3866
commit 2e47970a97
3 changed files with 67 additions and 31 deletions

View file

@ -3,31 +3,42 @@
This section provides some notes on how to hack on Hydra. To get the This section provides some notes on how to hack on Hydra. To get the
latest version of Hydra from GitHub: latest version of Hydra from GitHub:
```console
$ git clone git://github.com/NixOS/hydra.git $ git clone git://github.com/NixOS/hydra.git
$ cd hydra $ cd hydra
```
To enter a shell in which all environment variables (such as PERL5LIB) To enter a shell in which all environment variables (such as PERL5LIB)
are set up so that those dependencies can be found: are set up so that those dependencies can be found:
```console
$ nix-shell $ nix-shell
```
To build Hydra, you should then do: To build Hydra, you should then do:
```console
[nix-shell]$ ./bootstrap [nix-shell]$ ./bootstrap
[nix-shell]$ configurePhase [nix-shell]$ configurePhase
[nix-shell]$ make [nix-shell]$ make
```
You start a local database, the webserver, and other components with You start a local database, the webserver, and other components with
foreman: foreman:
```console
$ foreman start $ foreman start
```
You can run just the Hydra web server in your source tree as follows: You can run just the Hydra web server in your source tree as follows:
```console
$ ./src/script/hydra-server $ ./src/script/hydra-server
```
You can run Hydra's test suite with the following: You can run Hydra's test suite with the following:
```console
[nix-shell]$ make check [nix-shell]$ make check
[nix-shell]$ # to run as many tests as you have cores: [nix-shell]$ # to run as many tests as you have cores:
[nix-shell]$ make check YATH_JOB_COUNT=$NIX_BUILD_CORES [nix-shell]$ make check YATH_JOB_COUNT=$NIX_BUILD_CORES
@ -35,6 +46,7 @@ You can run Hydra's test suite with the following:
[nix-shell]$ yath test [nix-shell]$ yath test
[nix-shell]$ # to run as many tests as you have cores: [nix-shell]$ # to run as many tests as you have cores:
[nix-shell]$ yath test -j $NIX_BUILD_CORES [nix-shell]$ yath test -j $NIX_BUILD_CORES
```
When using `yath` instead of `make check`, ensure you have run `make` When using `yath` instead of `make check`, ensure you have run `make`
in the root of the repository at least once. 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: To build Hydra and its dependencies:
```console
$ nix-build release.nix -A build.x86_64-linux $ nix-build release.nix -A build.x86_64-linux
```

View file

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

View file

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