Firehose
========

Firehose is a tool which reads yaml files (see the `examples/` directory) which
instruct the tool in how to perform integrations of upstream changes into a
Baserock definitions set.  It is meant to be used in conjunction with the
Baserock CD pipeline (Mason) to reduce the cognitive load on the systems
integration role, freeing brain cycles for more constructive development work.

Currently Firehose is limited to applying all of its inputs in a single
integration and it only supports the absolute-sha landing method (which assumes
a zero delta between upstream and what we need for Baserock) but for anything
where that holds true, Firehose can provide a valuable service pre-integrating
and running those integrations through a CD pipeline to gain confidence in the
proposed change.

Presently Required Instructions to Run Firehose
===============================================

Create a Baserock build image and log in. The version used for testing
of the instructions below was 15.10.

Make a firehose configuration file. For example:

    name: linux
    kind: firehose
    description: |
      This is an example for tracking Linux kernel master. Every time
	  firehose runs we will try and build the tip of the kernel.
    landing:
      repo: baserock:baserock/definitions
      baseref: master
      destref: myusername/firehose-kernel-test
      stratum: bsp-x86_64-generic
      chunk: linux-x86-64-generic
      method: absolute-sha1
    tracking:
      mode: follow-tip
      ref: refs/heads/master

One thing worth knowing is that the *destref* field can be anything,
and ideally should be a new branch which does not already exist.
The *landing* section describes the chunk to be updated and the
*tracking* section describes what part of the upstream repo to
look at.

    echo 'export GERRIT_USER="myusernameongerrit"' > ~/.bashrc
    echo 'export GERRIT_URL="gerrit.baserock.org"' >> ~/.bashrc
    echo 'export GIT_USERNAME="myusername"' >> ~/.bashrc
    echo 'export GIT_EMAIL="my@email"' >> ~/.bashrc
    echo 'export FIREHOSE_CONFIG_FILE="/root/myfirehoseconfigfile.yaml"' >> ~/.bashrc
    . ~/.bashrc

Make a configuration script:

    vi /usr/bin/firehose-config

And add the following:

    #!/bin/bash
    if [ ! $GERRIT_USER ]; then
        echo 'Please specify a Gerrit username'
        exit 1
    fi
    if [ ! $GERRIT_URL ]; then
        echo 'Please specify a Gerrit URL'
        exit 2
    fi
    if [ ! $GIT_EMAIL ]; then
        echo 'Please specify a git email'
        exit 3
    fi
    if [ ! $GIT_USERNAME ]; then
        echo 'Please specify a git username'
        exit 4
    fi
    if [ ! $FIREHOSE_CONFIG_FILE ]; then
        echo 'Please specify a firehose configuration file'
        exit 5
    fi
    # install the latest morph
    mkdir /src
    cat > /src/morph.conf <<'EOF'
    [config]
    log = /src/morph.log
    log-max = 100M
    cachedir = /src/cache
    tempdir = /src/tmp
    artifact-cache-server = http://cache.baserock.org:8080/
    EOF
    mv /etc/morph.conf /etc/morph.dist.conf
    ln -sv /src/morph.conf /etc/morph.conf
    cd /src
    git clone http://bashrc@gerrit.baserock.org/baserock/baserock/morph
    if [ ! "$?" = "0" ]; then
        echo 'Failed to clone morph'
        exit 3
    fi
    cd morph
    cd /usr/bin
    mv morph morph.dist
    cat >morph <<'EOF'
    #!/bin/sh
    morphpath=/src/morph
    PYTHONPATH="$morphpath" "$morphpath/morph" "$@"
    EOF
    chmod +x morph
    cd /src/morph
    python setup.py install
    # Add firehose user
    adduser "$GERRIT_USER" -s /bin/false -D
    su -c "ssh-keygen -C $GERRIT_USER@baserock.org -N \"\"" - $GERRIT_USER
    chown -R "$GERRIT_USER":"$GERRIT_USER" /var/lib/firehose
    cd /home/$GERRIT_USER/
    # Clone the Firehose repo
    if [ ! -d /home/$GERRIT_USER/firehose ]; then
        git clone git://git.baserock.org/baserock/baserock/firehose
    fi
    cd firehose
    git checkout baserock/bmottram/firehose
    # Move Firehose arguments to specific directory and timer/service
    # files to /etc/systemd
    mkdir -p "/var/lib/firehose"
    cp examples/*.yaml "/var/lib/firehose/"
    cp firehose.service "/etc/systemd/system/firehose.service"
    cp firehose.timer "/etc/systemd/system/firehose.timer"
    sed -i "s|/home/firehose|/home/$GERRIT_USER|g" /etc/systemd/system/firehose.service
    sed -i "s|User=.*|User=$GERRIT_USER|g" /etc/systemd/system/firehose.service
    sed -i "s|/home/firehose/firehose/examples/linux-master.yaml|$FIREHOSE_CONFIG_FILE|g" /etc/systemd/system/firehose.service
    # Run the Firehose install script
    python ./setup.py install
    echo '[config]' > /etc/morph.conf
    echo "repo-alias=baserock=git://git.baserock.org/baserock/#ssh://$GERRIT_USER@$GERRIT_URL:29418/baserock/,upstream=git://git.baserock.org/delta/#ssh://$GERRIT_USER@$GERRIT_URL:29418/delta/" >> /etc/morph.conf
    # This will run Firehose on the argument specified in firehose.timer
    # automatically every six hours
    systemctl enable firehose.timer
    systemctl start firehose.timer
    systemctl enable firehose.service
    # Check necessary parameters were filled in firehose.morph before
    # the system was deployed, and exit if not
    if [[ -z "$GERRIT_USER" && -z "$GERRIT_URL" && -z "$GIT_USERNAME" && -z "$GIT_EMAIL" && -z "$FIREHOSE_CONFIG_FILE" ]]; then
        exit 0
    fi
    # Create firehose.conf to store parameters obtained from .morph file
    echo '[config]' > /etc/firehose.conf
    echo "gerrit_username = $GERRIT_USER" >> /etc/firehose.conf
    echo "gerrit_url = $GERRIT_URL" >> /etc/firehose.conf
    echo "git_username = $GIT_USERNAME" >> /etc/firehose.conf
    echo "git_email = $GIT_EMAIL" >> /etc/firehose.conf
    # Configure a git identity for Firehose
    su -c "echo \"git config --global user.name $GIT_USER\" > /home/$GERRIT_USER/.gitconfig" - $GERRIT_USER
    su -c "echo \"git config --global user.email $GIT_EMAIL\" >> /home/$GERRIT_USER/.gitconfig" - $GERRIT_USER
    echo 'Upload this public key to your gerrit user account settings:'
    cat /home/$GERRIT_USER/.ssh/id_rsa.pub
    exit 0

Then run the script:

    chmod +x /usr/bin/firehose-config
    firehose-config

Check that the service is running:

    systemctl status firehose

Make sure that your ssh public key is registered within your gerrit
user account.


Why is there Debian code in this repo?
======================================
To compare release version tags within repos some Debian code is
used, which can be found within the *debian* directory. Only the
version compare function is relevant here. The rest of the Debian
stuff isn't used.