Using Artifactory - tooltwist/documentation GitHub Wiki
NOTE: This page is now obsolete. See Deploying with the v8.3 Controller and related pages.
What is Artifactory?
Artifactory is a place to store the JAR files for a project, for ToolTwist, and for the many open source libraries we use. It provides several roles:
- allows everyone to access the jars.
- caches the jar files, allowing faster builds.
- restricts access to the jars of our customer's private projects.
- simplifies build scripts by using a single virtual repository, instead of multiple remote repositories.
Artifactory has an administration web interface, used by an administrator to add and remove repositories for each of our projects (probably Ryan or Phil). Each developer is given an account allowing them to access Artifactory and the repositories it hosts. See http://repo.tooltwist.com/artifactory.
Our Artifactory Servers
ToolTwist jars can be accessed from http://repo.tooltwist.com/artifactory/tooltwist-all-in-one. This is a server hosted on AWS, external to the office.
To provide faster builds in the Twist Resources office, we will be setting up another Artifactory server on the LAN which will cache jars from the main repository above. Note: this isn't available yet (Phil 2014-06-01)
Setting up for Gradle and Artifactory
First, you need Gradle installed on your machine.
User Properties file
Repository definitions, user names and passwords must not be stored in the build.gradle file or any other files that get checked into Github. This is super important!!!.
Instead, we define them in the user-specific gradle properties file ~/.gradle/gradle.properties.
First we define how to access ToolTwist and other common jars.
# Credentials to resolve ToolTwist artifacts
TOOLTWIST_ARTIFACTORY_CONTEXTURL=http\://repo.tooltwist.com/artifactory/
TOOLTWIST_ARTIFACTORY_REPO=tooltwist-all-in-one
TOOLTWIST_ARTIFACTORY_USER=...
TOOLTWIST_ARTIFACTORY_PASSWORD=...
Next we define the repositories for any specific projects. It's a good idea to leave a warning message in place, like this:
# PRIVATE PRIVATE PRIVATE PRIVATE PRIVATE PRIVATE
# Credentials to publish Acme jars and artifacts
#
# WARNING!!! Do not share these around!!!!
#
ACME_PUBLISH_ARTIFACTORY_CONTEXTURL=http\://repo.tooltwist.com/artifactory/
ACME_PUBLISH_RESOLVE_REPO=acme
ACME_PUBLISH_SNAPSHOT_REPO=acme-snapshot-local
ACME_PUBLISH_RELEASE_REPO=acme-release-local
ACME_PUBLISH_ARTIFACTORY_USER=...
ACME_PUBLISH_ARTIFACTORY_PASSWORD=...
# PRIVATE PRIVATE PRIVATE PRIVATE PRIVATE PRIVATE
These are examples only. Ask the artifactory administrator for a user name. To get the encrypted password, log into artifactory and click on your name next to Logged in as. Enter your password and press the Unlock button. You encrypted password will be displayed.
Project properties file
You will also need to set build properties related to your project. These can be placed in properties.gradle in the directory of your project.
PROJECT_SOURCE_COMPATIBILITY=1.7
PROJECT_GROUP=com.tooltwist
#PROJECT_VERSION=8.3.2-SNAPSHOT
PROJECT_VERSION=8.3.2
By changing the commented out version property, you can publishing to the snapshot repository during development, and then to the release repository when you have a stable version.
Note that in future we'll use Continuous Integration and Judson to build all snapshot jars.
The build script (build.gradle)
This wiki page won't try to explain how to write gradle build scripts. In most cases you can simply copy the build script from a different ToolTwist project and make changes. The following section shows how to add the artifactory sections to an existing build.gradle file.
Including the Artifactory plugin in your build script
Add the following to the top of your build.gradle.
apply plugin: 'artifactory'
This plugin will need java classes to work, and these can be pulled down from the ToolTwist repo like this:
buildscript {
repositories {
maven {
url TOOLTWIST_ARTIFACTORY_CONTEXTURL + TOOLTWIST_ARTIFACTORY_REPO
credentials {
username = "${TOOLTWIST_ARTIFACTORY_USER}"
password = "${TOOLTWIST_ARTIFACTORY_PASSWORD}"
}
}
mavenCentral()
}
dependencies {
classpath(group: 'org.jfrog.buildinfo', name: 'build-info-extractor-gradle', version: '2.0.9')
}
}
Defining the repositories
This section replaces the normal repositories section in a build.gradle file.
version = ...
// Remember whether this is a snapshot or release,
// so we publish it to the correct repository.
project.ext.isSnapshot = version.endsWith("-SNAPSHOT")
...
artifactory {
publish {
repository {
contextUrl = "${TOOLTWIST_PUBLISH_ARTIFACTORY_CONTEXTURL}"
repoKey = isSnapshot ? "${TOOLTWIST_PUBLISH_SNAPSHOT_REPO}" : "${TOOLTWIST_PUBLISH_RELEASE_REPO}"
username = "${TOOLTWIST_PUBLISH_ARTIFACTORY_USER}"
password = "${TOOLTWIST_PUBLISH_ARTIFACTORY_PASSWORD}"
maven = true
ivy {
ivyLayout = '[organization]/[module]/ivy-[revision].xml'
artifactLayout = '[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]'
mavenCompatible = true
}
}
defaults {
publishConfigs('archives', 'published')
properties = ['build.status': "$it.project.status".toString()]
}
}
resolve {
repository {
contextUrl = "${TOOLTWIST_ARTIFACTORY_CONTEXTURL}"
repoKey = "${TOOLTWIST_ARTIFACTORY_REPO}"
username = "${TOOLTWIST_ARTIFACTORY_USER}"
password = "${TOOLTWIST_ARTIFACTORY_PASSWORD}"
maven = true
}
}
}
When code is being compiled, the resolve section is used to find the dependencies. This will typically refer to a 'virtual' repository that Artifactory maps onto multiple remote repositories. An example is http://repo.tooltwist.com/artifactory/tooltwist-all-in-one.
Once the build is complete, jars and other artifacts can be loaded up to Artifactory to a repository defined in the publish section.
If the version number is specified as a snapshot, such as 3.1-SNAPSHOT, then the version number will be converted by Artifactory into a timestamp, such as 8.3.1-20140603.100833-1. When a project provides a version number ending with "-SNAPSHOT" it will automatically pull down the latest snapshot version.
Snapshots are used in development, where the code is updating constantly and we need to build or test against the latest version. In all other cases, a release version should be used. Note that it is essential that snapshots are not used in production. We place the snapshot and release versions of jar files in different repositories to prevent them getting confused.
The person looking after Artifactory can provide you with the names of the repositories for your project.
A Simplistic build script
The artifactory plugin described above is useful mostly when you wish to publish jars and other artifacts. For a simple project it might not be needed. In this simple build script, we resolve our dependencies using jars stored in our Artifactory repository, but we do no publishing.
apply plugin: 'java'
apply plugin: 'maven'
group 'com.phil.stuff'
version "1.0"
dependencies {
compile(group: 'commons-lang', name: 'commons-lang', version: '2.6')
compile(group: 'org.apache.lucene', name: 'lucene-core', version: '2.2+')
compile(group: 'com.phil.junk', name: 'a', version: '1.0')
compile(group: 'com.tooltwist', name: 'xdata', version: '8.3+')
}
repositories {
maven {
url "http://repo.tooltwist.com/artifactory/tooltwist-all-in-one"
}
}
A few things to note:
- This single repository can be use to access ToolTwist jars and also most other jars. This is possible because it is a 'virtual' repository, and actually maps onto multiple external repositories.
- The repository is in Maven format. We do not use the Ivy or Gradle formats available in Artifactory.
- This project does not publish anything to the repository.
--