Under the hood: Javadocs

This blog-post is about a minor topic as my main work from this week didn’t land in the master tree yet.

How to enable automatic javadoc creation using Travis-ci

I wanted to have a way to have the javadocs of loklak automatically build and published. That’s what many other java projects do and it often helps me alot to find docs through a search engine on the web. In the end I found a nice discription to do it.

As you probably know, we use an automatic build system for loklak. It’s called travis-ci and is directly offered by github.

If you want to use it for your own github repo, just go to the repo settings, select “Webhooks & services” and click “add service”. You will find travis-ci in the list there.

The build can be triggered by different events, most notably on pull requests, so before the code is merged into the target branch. This helps us alot to make sure a PR does not break anything.

The second, in our project barely noticed one, is the one afterwards, which is triggered everytime a commit is pushed to the master branch. Until recently, we didn’t really make use of that, as we only wanted to make sure the build works. The result itself was not used afterwards.

Another project of github is github.io. When activated for a repo (you can do it from Settings->Options->Github Pages), it creates a ‘gh-pages’ branch in you repo that contains html content, which is then displayed on github.io. So what we want to do is build the javadocs and push them to that specific branch.

In .utility/push-javadoc-to-gh-pages.sh we now have a script with the following content:

#!/bin/bash

if [ “$TRAVIS_REPO_SLUG” = “loklak/loklak_server” ] && [ “$TRAVIS_JDK_VERSION” = “oraclejdk8” ] && [ “$TRAVIS_PULL_REQUEST” = “false” ] && [ “$TRAVIS_BRANCH” = “master” ]; then

echo -e “Creating javadoc…n”

ant javadoc

echo -e “Publishing javadoc…n”

cp -R html/javadoc $HOME/javadoc-latest

cd $HOME
git config –global user.email “[email protected]
git config –global user.name “travis-ci”
git clone –quiet –branch=gh-pages https:[email protected]/loklak/loklak_server gh-pages > /dev/null

cd gh-pages
git rm -rf ./*
cp -Rf $HOME/javadoc-latest/* ./
git add -f .
git commit -m “Latest javadoc on successful travis build $TRAVIS_BUILD_NUMBER auto-pushed to gh-pages”
git push -fq origin gh-pages > /dev/null 2>&1

if [ $? -eq 0 ]; then
echo -e “Published Javadoc to gh-pages.n”
exit 0
else
echo -e “Publishing failed. Maybe the access-token was invalid or had insufficient permissions.n”
exit 1
fi

fi

When run, it checks if it’s in the loklak repo, is not a pull request and the build process happens on the master branch. It then calls ant to build the javadocs (note the build target javadoc in the ant build file).

It then removes the old content of the gh-pages branch and adds the new one, commits and pushes it. The interesting point here is the cloning part. Note the variable ${GH_TOKEN}.

Here’s the actuall magic in the story. We have a public visible script that somehow contains an access-token to in this case my github account. How can this be save?

Let’s have a look at our travis.yml file:

language: java

jdk:
– oraclejdk8

env:
global:
  – secure: “DbveaxDMtEP+/Er6ktKCP+P42uDU8xXWRBlVGaqVNU3muaRmmZtj8ngAARxfzY0f9amlJlCavqkEIAumQl9BYKPWIra28ylsLNbzAoCIi8alf9WLgddKwVWsTcZo9+UYocuY6UivJVkofycfFJ1blw/83dWMG0/TiW6s/SrwoDw=”

script:
– ./gradle_init.sh
– gradle assemble
– ./gradle_clean.sh
– ant
– bin/start.sh

install: true

branches:
only:
– “master”

after_success:
– sh .utility/push-javadoc-to-gh-pages.sh

We see that the script from above is called if the process was successfull. So what’s that “secure” part?

Travis offers a very interesting way to let us put code into their build file that can’t be seen by outsider. It works with public/private key encryption. Travis creates a key-pair for each repo.

With their ruby-tool (also called travis), we can easily encrypt data with the public key by calling

travis encrypt some-data

from the corresponding git-folder and adding the output to the build-file. So when Travis reads the build-file and finds the secure-block, it uses the private key (that only travis knows) to decrypt the data. As the key pair is only used for this repo, it only works when called from there.

So we have a way to give Travis data only it can use. The actual encryption command looked somhow like:

travis encrypt GH_TOKEN=323pthaid123ntahoeudi

We saved some access-token in the variable GH_TOKEN, that we then use later in the script.

That’s it, you can now always see the latest javadocs at http://loklak.github.io/loklak_server/

Under the hood: Javadocs