@ -26,12 +26,16 @@ Preparing the Gitian builder host
The first step is to prepare the host environment that will be used to perform the Gitian builds.
This guide explains how to set up the environment, and how to start the builds.
Gitian offers to build with either `kvm`, `docker` or `lxc`. The default build
path chosen is `lxc`, but its setup is more complicated. You need to be logged in as the `gitianuser`.
If this user does not exist yet on your system, create it. Gitian can use
either kvm, lxc or docker as a host environment. This documentation will show
how to build with lxc and docker. While the docker setup is easy, the lxc setup
is more involved.
* Gitian host OS should be Ubuntu 18.04 "Bionic Beaver". If you are on a mac or windows for example, you can run it in a VM but will be slower.
* Gitian gives you the option of using any of 3 different virtualization tools: `kvm`, `docker` or `lxc`. This documentation will only show how to build with `lxc` and `docker` (documentation for `kvm` is welcome). Building with `lxc` is the default, but is more complicated, so we recommend docker your first time.
## Create the gitianuser account
You need to create a new user called `gitianuser` and be logged in as that user. The user needs `sudo` access.
LXC
---
@ -76,10 +80,17 @@ This setup is required to enable networking in the container.
Docker
------
Building in docker does not require much setup. Install docker on your host, then type the following:
Prepare for building with docker:
```bash
sudo apt-get install git make curl
sudo apt-get install git make 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/):
```bash
sudo groupadd docker
sudo usermod -aG docker gitianuser
```
Optionally add yourself to the docker group. Note that this will give docker root access to your system.
@ -88,7 +99,7 @@ Optionally add yourself to the docker group. Note that this will give docker roo
sudo usermod -aG docker gitianuser
```
Manual and Building
Manual Building
-------------------
The instructions below use the automated script [gitian-build.py](gitian-build.py) which only works in Ubuntu.
@ -109,66 +120,95 @@ The `gitian-build.py` script will checkout different release tags, so it's best
cp monero/contrib/gitian/gitian-build.py .
```
Setup the required environment, you only need to do this once:
### Setup the required environment
Setup for LXC:
```bash
./gitian-build.py --setup fluffypony v0.14.0
GH_USER=fluffypony
VERSION=v0.14.1.0
./gitian-build.py --setup $GH_USER $VERSION
```
Where `fluffypony` is your Github name and `v0.14.0` is the version tag you want to build.
If you are using docker, run it with:
Where `GH_USER` is your Github user name and `VERSION` is the version tag you want to build.
While gitian and this build script does provide a way for you to sign the build directly, it is recommended to sign in a seperate step.
This script is only there for convenience. Seperate steps for building can still be taken.
While gitian and this build script does provide a way for you to sign the build directly, it is recommended to sign in a separate step. This script is only there for convenience. Separate steps for building can still be taken.
In order to sign gitian builds on your host machine, which has your PGP key,
fork the gitian.sigs repository and clone it on your host machine,
fork the [gitian.sigs repository](https://github.com/monero-project/gitian.sigs) and clone it on your host machine,
or pass the signed assert file back to your build machine.
To build the most recent tag (pass in `--docker` after setting up with docker):
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.
To build the most recent tag (pass in `--docker` if using docker):
To speed up the build, use `-j 5 -m 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 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.
If all went well, this produces a number of (uncommited) `.assert` files in the gitian.sigs repository.
If all went well, this produces a number of (uncommitted) `.assert` files in the gitian.sigs directory.
If you do detached, offline signing, you need to copy these uncommited changes to your host machine, where you can sign them. For example:
Checking your work
------------------
Take a look in the assert files and note the SHA256 checksums listed there. eg for `v0.14.1.0` you should get this checksum:
You should verify that this is really the checksum you get on that file you built. You can also look in the 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.
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:
**Note:** Please ensure your gpg public key is available to check signatures by adding it to the [gitian.sigs/gitian-pubkeys/](https://github.com/monero-project/gitian.sigs/tree/master/gitian-pubkeys) directory in a pull request.
Jonathan Cross
5 years ago