Improve the README

Change-Id: I7957ef42813ef51319f6c67b2ca9aab951ff5e71

1 files changed, 156 insertions, 52 deletions

diff --git a/README b/README
index 8a0b36b..e9b1d11 100644
--- a/README
+++ b/README
@@ -17,55 +17,159 @@ proposed change.
 Presently Required Instructions to Run Firehose
 ===============================================
 
-Firehose deployment isn't automated yet. Here are instructions on how to do it
-manually:
-
-In a 'build' machine in the cloud:
-
- morph build systems/build-system-x86_64.morph
- morph deploy baserock-firehose/baserock-firehose.morph
-
-Instatiate this image and SSH into it.
-
- git clone git://git.baserock.org/baserock/baserock/firehose
- git checkout baserock/lauren/firehose
- python ./setup.py install
- adduser firehose -s /bin/false -D
- sudo -u firehose -- ssh-keygen -C 'firehose@baserock.org' -N ''
- sudo chown -R firehose:firehose /var/lib/firehose
-
-Create an account on the Gerrit instance where Firehose will be pushing:
-
- ssh -p 29418 you@gerrit.baserock.org gerrit \
- create-account --group "'Non-Interactive Users'" \
- --ssh-key xxxx --full-name "'Firehose integration tool'" \
- --email='firehose@firehose.baserock.org' \
- firehose
-
-Test that the Firehose user can connect to Gerrit (this should give you a help
-message if successful, or a 'Permission denied' error otherwise):
-
- sudo -u firehose -- ssh -p 29418 firehose@gerrit.baserock.org gerrit
-
-Move firehose.service and firehose.timer files to /etc/systemd/system/
-
-Run:
-
- systemctl enable firehose.timer
- systemctl start firehose.timer
- systemctl enable firehose.service
-
-As Firehose, ensure that the git config matches what gerrit expects W.R.T email address, i.e.
-
- git config --global user.email firehose@firehose.baserock.org
-
-If Firehose fails due to an error in /tmp/morph_tmp/, edit /etc/morph.conf to include the following:
-
- [config]
- repo-alias=baserock=git://git.baserock.org/baserock/#ssh://firehose@testgerrit.baserock.org:29418/baserock/,upstream=git://git.baserock.org/delta/#ssh://firehose@testgerrit.baserock.org:29418/delta/
-
-Comparing tags within repos
-===========================
-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.
+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.