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.

4 Launching

This chapter describes how Ratpack applications are started, effectively detailing the entry points to the Ratpack API.

4.1 RatpackServer

The RatpackServer type is the Ratpack entry point. You write your own main class that uses this API to launch the application.

package my.app;

import ratpack.server.RatpackServer;
import ratpack.server.ServerConfig;
import java.net.URI;

public class Main {
  public static void main(String... args) throws Exception {
    RatpackServer.start(server -> server
      .serverConfig(ServerConfig.embedded().publicAddress(new URI("http://company.org")))
      .registryOf(registry -> registry.add("World!"))
      .handlers(chain -> chain
        .get(ctx -> ctx.render("Hello " + ctx.get(String.class)))
        .get(":name", ctx -> ctx.render("Hello " + ctx.getPathTokens().get("name") + "!"))     
      )
    );
  }
}

Applications are defined as the function given to the of() or start() static methods of this interface. The function takes a RatpackServerSpec which can be used to specify the three fundamental aspects of Ratpack apps (i.e. server config, base registry, root handler).

Most examples in this manual and the API reference use EmbeddedApp instead of RatpackServer to create applications. This is due to the “testing” nature of the examples. Please see this section for more information regarding the code samples.

4.1.1 Server Config

The ServerConfig defines the configuration settings that are needed in order to start the server. The static methods of ServerConfig can be used to create instances.

4.1.1.1 Base dir

An important aspect of the server config is the base dir. The base dir is effectively the root of the file system for the application. All relative paths will be resolved via the base dir. Static assets (e.g. images, scripts) are typically served via the base dir.

4.1.2 Registry

A registry is a store of objects stored by type. There may be many different registries within an application, but all applications are backed a “server registry”. A server registry is just the name given to the registry that backs the application and is defined at launch time.

4.1.3 Handler

The server handler receives all incoming HTTP requests. Handlers are composable, and very few applications are actually comprised of only one handler. The server handler for most applications is a composite handler, typically created by using the handlers(Action) method, that uses the Chain DSL to create the composite handler.