1.1 via SSH

In many cases, we have SSH/SFTP access to a web server, which is configured so that files and directories copied into a certain location will be served and mapped onto URLs. For example, on the CS Linux network, files stored in /home/yourName/secure_html/whatever are served at the URLs https://www.cs.odu.edu/~yourName/whatever.

1.2 via git branches

GitHub provides a web server (called GitHub Pages) for projects hosted on it. A project hosted at https://github.com/owner/project will have web pages hosted at https://owner.github.io/project/.

But GitHub has adopted a very different approach to deployment. When you activate GitHub Pages for your project, you specify a specific git branch to manage your website content. By default, this branch is named gh-pages.

2 Automating Website Deployment with Gradle

Suppose that we have set up Gradle to build our website in build/jbake/ using a task named bake.

2.1 An SSH solution

Gradle plugin org.hidetake:gradle-ssh-plugin allows you to

• Use scp to upload or download one file at a time from/to a remote server.
• Use ssh to issue commands to a remote server.

A plausible set of Gradle steps:

1. Create a .zip file of the entire constructed website
2. Use scp to upload the zip file to the remote server.
3. Use ssh to issue an unzip command on the remote server.
4. If necessary, use ssh to issue chmod commands as necessary on the unzipped content.

build.gradle

plugins {
  id 'org.hidetake.ssh' version '2.9.0'
}

task zipWebsite (type: Zip, dependsOn: 'bake') {   ➀
    archiveFileName = 'website.zip'
    destinationDirectory = file('build')
    from 'build/jbake'
}

remotes {
  webServer {
    host = IP address
    user = userName
    identity = file(ssh-private-key)  ➁
  }
}

task deploy (dependsOn: 'zipWebsite') {
  doLast {
    ssh.run {
      session(remotes.webServer) {
       put from: 'build/website.zip', into: 'websitePath' ➂
       execute 'unzip websitePath/website.zip' -d websitePath➃
      }
    }
  }
}

• ➀ zip up the website (assuming our earlier Jbake example)
• ➁ assumes this key is in a running key agent (or passphrase-free)
• ➂ Copy the zip file to the remote host
• ➃ Tell the remote host to unpack the zip file

2.2 An rsync Solution

The Java library rsync4j-all provides a Java interface to rsync:

2.3 A GitHub Solution

GitHub’s “Pages” services hosts websites by allowing the repository owner to specify a branch that will hold the website contents. The static (unchanging) components of a website could simply be constructed and committed “manually”, but dynamic contents that depend upon the build will necessarily involve some git manipulation.

In this section we look at the standard approach that GitHub intended - using one or more branches for the main project content and a separate “special” branch for the website.

2.3.1 A Portable Approach using a Git Plugin

The Gradle plugin org.xbib.gradle.plugin.git provides a portable interface to a java library implementation git.

Unfortunately, the version of git provided does not support multiple workspaces for a repository. So I need to modify the approach I described earlier.

1. Clone the repository in our project root directory into build/gh-pages/ and check out the gh-pages branch in that clone.

   Note that because this is a clone of a local repository, the new repository will have the local repository in the project root as its origin. (The project root repository, presumably, has the remote GitHub repository as its origin). So pushes and pulls to the build/gh-pages/ repository will go to the project root repository, not directly to GitHub.

2. Delete all files inside build/gh-pages/.

3. Copy all files from build/jbake to the build/gh-pages/.

   If your own website contents are in a different directory, or are split among multiple directories, you might need to add some additional copy steps.

4. Commit those changes (to the gh-pages branch).

5. Push that commit in the build/gh-pages/ repository to the project root repository.

build.gradle

plugins {
    ⋮
    id "org.xbib.gradle.plugin.git" version "2.0.0"
    ⋮
}


    ⋮



////////  Website publication on GitHub pages ///////////////////


task clonePages() {                                             ➀
    doLast {
        mkdir 'build/gh-pages'
        def thisRepo = rootProject.projectDir.toString()
        def pagesDir = "$buildDir/gh-pages"
        project.delete {
            delete pagesDir
        }
        def grgit = git.clone {
            dir = pagesDir
            uri = 'file:' + thisRepo
            bare = false
            refToCheckout = 'gh-pages'
        }
        grgit.checkout {
            branch = 'gh-pages'
        }
        grgit.close()
    }
}

task copyReports (type: dependsOn: ['bake', 'clonePages']) {  ➁
    doLast {
        ant.copy (todir: 'build/gh-pages') {
            fileset(dir: 'build/jbake')
        }
    }
}

task updateGHPages (dependsOn: 'copyReports') {                     ➂
    group = "Reporting"
    description  'Copies reports to the gh-pages branch in preparation for a future push to GitHub'
    doLast {
        def pagesDir = "$buildDir/gh-pages"
        def grgit = git.open {
            dir = pagesDir + "/.git"
        }
        grgit.add (update: false, patterns: ['reports/'])
        grgit.add (update: true, patterns: ['reports/'])
        grgit.commit {
            message = "Updating web pages"
        }
        grgit.push {}
        grgit.close()
    }
}

2.3.2 A Less-Portable Approach using Native Git Commands

I have to admit that I find the git plugin to be a bit tedious to work with. If we know that the only machines that we will be running on will have a native version of git, we can simplify the above by letting gradle invoke git directly. This is accomplised via the gradle exec command, which can run a native OS command in a specified working directory:

////////  Website publication on GitHub pages ///////////////////


task clonePages() {
    doLast {
        mkdir 'build/gh-pages'
        def thisRepo = rootProject.projectDir.toString()
        def pagesDir = "$buildDir/gh-pages"
        project.delete {
            delete pagesDir
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'clone', 'file:' + thisRepo]
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'checkout', 'gh-pages']
        }
    }
}

task copyReports (type: dependsOn: ['bake', 'clonePages']) {
    doLast {
        ant.copy (todir: 'build/gh-pages') {
            fileset(dir: 'build/jbake')
        }
    }
}

task updateGHPages (dependsOn: 'copyReports') {
    group = "Reporting"
    description  'Copies reports to the gh-pages branch in preparation for a future push to GitHub'
    doLast {
        def pagesDir = "$buildDir/gh-pages"
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'add', '.']
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'commit', '-m', 'Updating-webpages']
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'push']
        }
    }
}

The exec commands allow us to give a shell command as an array of string values. You can see that the steps performed are largely the same as in the plugin-based solution.

I find the resulting tasks to be much easier to read. In general, though, I advise caution in using exec because it is potentially less portable.

2.4 Case Study: a Github Solution for Free Accounts

If you are working with a private repository from a free account, then Github pages will not be available to you.

A workaround is to create a second, public, repository whose only purpose is to host the website. Becausethis second repository will not have anything in it but the web content (which was always going to be public anyway), there’s no great loss of security in making this second repository public.

The second repository can also be simpler. It doesn’t need multipel branches to separate the project code from the website, bcause no project code will be stored there. So we can tell Github to use the main branch as the source of the website.

The gradle code for this modified approach is quite similar to the previous approach:

////////  Website publication on GitHub pages ///////////////////


def websiteRepo='git@github.com:sjzeil/pages-sandbox.git'    ➀

task clearPages(type: Delete) {
    delete 'build/gh-pages'
}

task clonePages(dependsOn: ['clearPages']) {                ➁
    doLast {
        exec {
            workingDir = '.'
            commandLine = ['git', 'clone', websiteRepo, 'build/gh-pages']
        }
    }
}


task copyWebsite (dependsOn: ['reports', 'clonePages']) {   ➂
    doLast {
        ant.copy (todir: 'build/gh-pages') {
            fileset(dir: 'build/reports')
        }
        ant.copy (todir: 'build/gh-pages') {
            fileset(dir: 'build/docs')
        }
        ant.copy (todir: 'build/gh-pages') {
            fileset(dir: 'src/main/html')
        }
    }
}



task updateGHPages (dependsOn: 'copyWebsite') {
    group = "Reporting"
    description  'Copies reports to the gh-pages branch in preparation for a future push to GitHub'
    doLast {
        def pagesDir = "$buildDir/gh-pages"
        exec {
            workingDir = 'build/gh-pages'                                ➃
            commandLine = ['git', 'add', '.']
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'commit', '-m', 'Updating-webpages']   ➄
        }
        exec {
            workingDir = 'build/gh-pages'
            commandLine = ['git', 'push']
        }
    }
}

• ➀ Here we provide the git URL to clone the second repository.
• ➁ We clone second repository. One again, we will putthe clone within our build/ directory, as we do with all autoamtically generated build products.
• ➂ We copy the web content, both static and dynamic, into the cloned area.
• ➃ We tell git to stage all of the files we have copied.
• ➄ Finally, we commit and then push.

Unlike our previous examples, this action deploys the website content immediately. We do not have to issue a separate push afterwards.