Doc: Update Gitian (Reproducible Builds) with small code snippets and fixes

1 files changed, 52 insertions, 18 deletions

diff --git a/contrib/gitian/README.md b/contrib/gitian/README.md
index e2e1d0b94..0a40d4608 100644
--- a/contrib/gitian/README.md
+++ b/contrib/gitian/README.md
@@ -36,6 +36,10 @@ This guide explains how to set up the environment, and how to start the builds.
 
 You need to create a new user called `gitianuser` and be logged in as that user.  The user needs `sudo` access.
 
+```bash
+sudo adduser gitianuser
+sudo usermod -aG sudo gitianuser
+```
 
 LXC
 ---
@@ -83,7 +87,7 @@ Docker
 Prepare for building with docker:
 
 ```bash
-sudo apt-get install git make curl docker.io
+sudo bash -c 'apt-get update && apt-get upgrade -y && apt-get install git curl docker.io'
 ```
 
 Consider adding `gitianuser` to the `docker` group after reading about [the security implications](https://docs.docker.com/v17.09/engine/installation/linux/linux-postinstall/):
@@ -96,13 +100,12 @@ sudo usermod -aG docker gitianuser
 Optionally add yourself to the docker group. Note that this will give docker root access to your system.
 
 ```bash
-sudo usermod -aG docker gitianuser
+sudo usermod -aG docker $USER
 ```
 
 Manual Building
 -------------------
 
-The instructions below use the automated script [gitian-build.py](gitian-build.py) which only works in Ubuntu. 
 =======
 The script automatically installs some packages with apt. If you are not running it on a debian-like system, pass `--no-apt` along with the other
 arguments to it. It calls all available .yml descriptors, which in turn pass the build configurations for different platforms to gitian.
@@ -122,17 +125,23 @@ cp monero/contrib/gitian/gitian-build.py .
 
 ### Setup the required environment
 
-Setup for LXC:
+Common setup part:
 
 ```bash
-GH_USER=fluffypony
-VERSION=v0.17.0.0
+su - gitianuser
 
-./gitian-build.py --setup $GH_USER $VERSION
+GH_USER=YOUR_GITHUB_USER_NAME
+VERSION=v0.17.2.0
 ```
 
 Where `GH_USER` is your Github user name and `VERSION` is the version tag you want to build. 
 
+Setup for LXC:
+
+```bash
+./gitian-build.py --setup $GH_USER $VERSION
+```
+
 Setup for docker:
 
 ```bash
@@ -145,8 +154,10 @@ fork the [gitian.sigs repository](https://github.com/monero-project/gitian.sigs)
 or pass the signed assert file back to your build machine.
 
 ```bash
-git clone git@github.com:monero-project/gitian.sigs.git
-git remote add $GH_USER git@github.com:$GH_USER/gitian.sigs.git
+git clone https://github.com/monero-project/gitian.sigs/
+pushd gitian.sigs
+git remote add $GH_USER https://github.com/$GH_USER/gitian.sigs
+popd
 ```
 
 Build the binaries
@@ -154,13 +165,26 @@ Build the binaries
 
 **Note:** if you intend to build MacOS binaries, please follow [these instructions](https://github.com/bitcoin-core/docs/blob/master/gitian-building/gitian-building-mac-os-sdk.md) to get the required SDK.
 
+Currently working MacOS solution:
+
+```bash
+curl -O https://bitcoincore.org/depends-sources/sdks/MacOSX10.11.sdk.tar.gz
+mv MacOSX10.11.sdk.tar.gz builder/inputs
+```
+
 To build the most recent tag (pass in `--docker` if using docker):
 
 ```bash
 ./gitian-build.py --detach-sign --no-commit --build $GH_USER $VERSION
 ```
 
-To speed up the build, use `-j 5 --memory 5000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 5000 is a little bit less than then the MB's of RAM you allocated. If there is memory corruption on your machine, try to tweak these values.
+To speed up the build, use `-j 5 --memory 10000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 10000 is a little bit less than then the MB's of RAM you allocated. If there is memory corruption on your machine, try to tweak these values. A good rule of thumb is, that Monero currently needs about 2 GB of RAM per core. 
+
+A full example for `docker` would look like the following:
+
+```bash
+./gitian-build.py -j 5 --memory 10000 --docker --detach-sign --no-commit --build $GH_USER $VERSION
+```
 
 If all went well, this produces a number of (uncommitted) `.assert` files in the gitian.sigs directory.
 
@@ -171,6 +195,22 @@ Take a look in the assert files and note the SHA256 checksums listed there.
 
 You should verify that the checksum that is listed matches each of the binaries you actually built.
 This may be done on Linux using the `sha256sum` command or on MacOS using `shasum --algorithm 256` for example.
+An example script to verify the checksums would be:
+
+```bash
+pushd out/${VERSION}
+
+for ASSERT in ../../sigs/${VERSION}-*/*/*.assert; do
+  if ! sha256sum --ignore-missing -c "${ASSERT}" ; then
+    echo "FAILED for ${ASSERT} ! Please inspect manually."
+  fi
+done
+
+popd
+```
+
+Don't ignore the incorrect formatting of the found assert files. These files you'll have to compare manually (currently OSX and FreeBSD).
+
 
 You can also look in the [gitian.sigs](https://github.com/monero-project/gitian.sigs/) repo and / or [getmonero.org release checksums](https://web.getmonero.org/downloads/hashes.txt) to see if others got the same checksum for the same version tag.  If there is ever a mismatch -- **STOP! Something is wrong**.  Contact others on IRC / github to figure out what is going on.
 
@@ -181,14 +221,7 @@ Signing assert files
 If you chose to do detached signing using `--detach-sign` above (recommended), you need to copy these uncommitted changes to your host machine, then sign them using your gpg key like so:
 
 ```bash
-GH_USER=fluffypony
-VERSION=v0.17.0.0
-
-gpg --detach-sign ${VERSION}-linux/${GH_USER}/monero-linux-*-build.assert
-gpg --detach-sign ${VERSION}-win/${GH_USER}/monero-win-*-build.assert
-gpg --detach-sign ${VERSION}-osx/${GH_USER}/monero-osx-*-build.assert
-gpg --detach-sign ${VERSION}-android/${GH_USER}/monero-android-*-build.assert
-gpg --detach-sign ${VERSION}-freebsd/${GH_USER}/monero-freebsd-*-build.assert
+for ASSERT in sigs/${VERSION}-*/*/*.assert; do gpg --detach-sign ${ASSERT}; done
 ```
 
 This will create a `.sig` file for each `.assert` file above (2 files for each platform).
@@ -201,6 +234,7 @@ Make a pull request (both the `.assert` and `.assert.sig` files) to the
 [monero-project/gitian.sigs](https://github.com/monero-project/gitian.sigs/) repository:
 
 ```bash
+cd gitian.sigs
 git checkout -b $VERSION
 # add your assert and sig files...
 git commit -S -a -m "Add $GH_USER $VERSION"