This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

2 Setup

Ratpack is purely a runtime. There is no installable package. To build Ratpack applications, you can use any JVM build tool. The Ratpack project provides specific support for Gradle through plugins, but any could be used.

Ratpack is published as a set of library JARs. The ratpack-core library is the only strictly required library. Others such as ratpack-groovy, ratpack-guice, ratpack-jackson, ratpack-test etc. are optional.

With Ratpack on the classpath, you can use the API described in the next chapter to launch the application.

2.1 Using the Gradle plugin(s)

First, install Gradle if you haven’t already. On Mac OS X, if you have Homebrew installed, you can simply run brew install gradle.

2.1.1 Using the Gradle Java plugin

Create a build.gradle file with the following contents:

buildscript {
  repositories {
    jcenter()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:0.9.9"
  }
}

apply plugin: "io.ratpack.ratpack-java"
apply plugin: "idea"

repositories {
  jcenter()
}

dependencies {
  runtime "org.slf4j:slf4j-simple:1.7.5"
}

Create directories src/ratpack and src/main/java.

If desired, run gradle idea to generate project files for IntelliJ and open the project.

Create a src/ratpack/ratpack.properties file with the following contents:

handlerFactory=AppHandlerFactory

Create a src/main/java/AppHandlerFactory.java with the following contents:

import ratpack.handling.Context;
import ratpack.handling.Handler;
import ratpack.launch.HandlerFactory;
import ratpack.launch.LaunchConfig;

import static ratpack.handling.Handlers.*;

public class AppHandlerFactory implements HandlerFactory {
  @Override
  public Handler create(LaunchConfig launchConfig) throws Exception {
    return chain(
      path("foo", new Handler() {
          @Override
          public void handle(Context context) {
              context.render("from the foo handler");
          }
      }),
      path("bar", new Handler() {
        @Override
        public void handle(Context context) throws Exception {
          context.render("from the bar handler");
        }
      })
    );
  }
}

Run the project by running gradle run, or create a distribution archive by running gradle distZip.

For further information on using Ratpack with Gradle, please the Gradle chapter.

2.1.2 Using the Gradle Groovy plugin

Create a build.gradle file with the following contents:

buildscript {
  repositories {
    jcenter()
  }
  dependencies {
    classpath "io.ratpack:ratpack-gradle:0.9.9"
  }
}

apply plugin: "io.ratpack.ratpack-groovy"
apply plugin: "idea"

repositories {
  jcenter()
}

dependencies {
  runtime "org.slf4j:slf4j-simple:1.7.5"
}

Create directories src/ratpack and src/main/groovy.

If desired, run gradle idea to generate project files for IntelliJ and open the project.

Create a src/ratpack/ratpack.groovy file with the following contents:

import static ratpack.groovy.Groovy.ratpack

ratpack {
    handlers {
        get("foo") {
            render "from the foo handler"
        }
        get("bar") {
            render "from the bar handler"
        }
    }
}

Run the project by running gradle run, or create a distribution archive by running gradle distZip.

For further information on using Ratpack with Gradle and Groovy, please the Gradle and Groovy chapters.

2.2 Using Lazybones project templates

Lazybones is a command line tool that allows you to generate a project structure for any framework based on pre-defined templates.

Ratpack’s Lazybones templates can be found on Bintray in the ratpack/lazybones repository. Templates are published with each Ratpack release and template versions are aligned with Ratpack release versions. There are different types of Ratpack templates available, listed in the repository. See the description of each for details.

See the Lazybones documentation for help with installing Lazybones.

Lazybones commands are in the format…

lazybones create <ratpack template> <ratpack version> <app name>

With Lazybones installed, creating a new Ratpack application is as easy as…

lazybones create ratpack my-ratpack-app
cd my-ratpack-app
./gradlew run

This will use the latest available version of Ratpack. If a specific version is required…

lazybones create ratpack x.x.x my-ratpack-app
cd my-ratpack-app
./gradlew run

Where x.x.x is a valid template version. See the Bintray template repository for all available template versions.