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.

1.4 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.core.server.RatpackServer;
import ratpack.core.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.

1.1.4 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.

1.1.1.4 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, providing a portable file system. All relative paths to be resolved to files during runtime will be resolved relative to the base dir. Static assets (e.g. images, scripts) are typically served via the base dir using relative paths.

The baseDir(Path) method allows setting the base dir to some known location. In order to achieve portability across environments, if necessary, the code that calls this is responsible for determining what the base dir should be for a given runtime.

It is more common to use BaseDir.find() that supports finding the base dir on the classpath, providing better portability across environments. This method searches for a resource on the classpath at the path "/.ratpack".

To use a different path than the /.ratpack default, use the BaseDir.find(String) method.

The contents of the marker file are entirely ignored. It is just used to find the enclosing directory, which will be used as the base dir. The file may be within a JAR that is on the classpath, or within a directory that is on the classpath.

The following example demonstrates using BaseDir.find() to discover the base dir from the classpath.

import ratpack.core.server.ServerConfig;
import ratpack.test.embed.EphemeralBaseDir;
import ratpack.test.embed.EmbeddedApp;

import java.net.URL;
import java.net.URLClassLoader;
import java.nio.file.Path;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class Example {
  public static void main(String... args) throws Exception {
    EphemeralBaseDir.tmpDir().use(baseDir -> {
      baseDir.write("mydir/.ratpack", "");
      baseDir.write("mydir/assets/message.txt", "Hello Ratpack!");
      Path mydir = baseDir.getRoot().resolve("mydir");

      ClassLoader classLoader = new URLClassLoader(new URL[]{mydir.toUri().toURL()});
      Thread.currentThread().setContextClassLoader(classLoader);

      EmbeddedApp.of(serverSpec -> serverSpec
        .serverConfig(c -> c.baseDir(mydir))
        .handlers(chain ->
          chain.files(f -> f.dir("assets"))
        )
      ).test(httpClient -> {
        String message = httpClient.getText("message.txt");
        assertEquals("Hello Ratpack!", message);
      });
    });
  }
}

The use of EphemeralBaseDir and the construction of a new context class loader are in the example above are purely to make the example self contained. A real main method would simply call BaseDir.find(), relying on whatever launched the Ratpack application JVM to have launched with the appropriate classpath.

Ratpack accesses the base dir via the Java 7 Path API, allowing transparent use of JAR contents as the file system.

2.1.1.4 Port

The port(int) method allows setting the port used to connect to the server. If not configured, the default value is 5050.

3.1.1.4 SSL

By default, the Ratpack server will listen for HTTP traffic on the configuration port. To enable HTTPS traffic, the ssl(SslContext) method allows for the SSL certificate and key.

As of v2.0, Ratpack also supports selecting SSL configurations based on the requested host using Server Name Indicators (SNI). The ssl(SslContext, Action) is used to specify the default SSL configuration and any additional domain mappings with alternative SSL configuration. The domains specified in the mapping support DNS Wildcard and will match at most one level deep in the domain hierarchy (e.g. *.ratpack.io will match api.ratpack.io but not docs.api.ratpack.io).

Configuring SSL settings via system properties or environment variables requires special handling to specify the domain names. The following table shows how to specify the default SSl configuration and the configuration for subdomains.

Note the following special rules: 1. In both system properties and environment variables, domain name separators (.) are converted into underscores (_) 2. In environment variables, the domain wildcard character (*) is specified using an underscore (_). This results in 3 underscores preceding the domain name (___RATPACK_IO).

2.1.4 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 by a “server registry”. A server registry is just the name given to the registry that backs the application and is defined at launch time.

3.1.4 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.

4.1.4 Start and stop actions

The Service interface allows hooking in to the application lifecycle. Before accepting any requests, Ratpack will notify all services and allow them to perform any initialization. Conversely, when the application stops, Ratpack will notify all services and allow them to perform any cleanup or termination.