Quickstart

This guide will go through the steps required to get a basic server up and running but will not cover the details of how to install and use an application on top of it. It may be more useful to find a similar guide for the application you are trying to use.

Step 1: Server kit

The server and client libraries come packaged in a single file with a name of the form terracotta-kit-VERSION.PACKAGE (examples would be terracotta-kit-5.2-SNAPSHOT.zip or terracotta-kit-5.2.0-pre4.tar.gz). This can be accessed with Maven coordinates: groupId: org.terracotta.internal, artifactId: terracotta-kit

Unpack the kit and enter the created directory. The current directory should now contain the following: README.txt, client, legal, server.

Step 2: Server on default config

Just to make sure that the server is working and finding Java correctly, run the start script: ./server/bin/start-tc-server.sh (note that this is .\server\bin\start-tc-server.bat, on Windows).

If this is working correctly, a few lines will be printed, one of them ending in now ready for work. If that appears, it means that the server is able to start but we don’t want to use the default config so kill this process.

Step 3: Creating a simple stripe config

Create a file called tc-config.xml, in the current directory, which contains the following text:

<tc-config xmlns="http://www.terracotta.org/config">
  <plugins>
  </plugins>
  <entities>
  </entities>
  <tc-properties/>
  <servers secure="false">
    <server host="localhost" name="testServer">
      <logs>logs</logs>
      <tsa-port>9000</tsa-port>
      <tsa-group-port>9001</tsa-group-port>
    </server>
    <client-reconnect-window>120</client-reconnect-window>
  </servers>
</tc-config>

This is a minimal configuration for a single-server stripe. It is called testServer and can be accessed, from a client, via terracotta://localhost:9000.

Step 4: Create very simple test client

Create a file called Test.java, in the current directory, containing the following text:

import java.io.IOException;
import java.net.URI;
import java.util.Properties;

import org.terracotta.connection.Connection;
import org.terracotta.connection.ConnectionException;
import org.terracotta.connection.ConnectionFactory;

public class Test {
  public static void main(String[] args) throws IOException, ConnectionException {
    URI uri = URI.create(args[0]);
    Properties emptyProperties = new Properties();
    Connection connection = ConnectionFactory.connect(uri, emptyProperties);
    System.out.println("Connection established!  " + connection);

    connection.close();
  }
}

Compile this class (note that the client-runtime JAR name depends on version): javac -cp client/lib/client-runtime-5.2-SNAPSHOT.jar Test.java

Step 5: Start the server and connect our client

We will be starting to processes so you probably want to use multiple terminals (or background the server).

Start the server: ./server/bin/start-tc-server.sh -n testServer

After the server prints now ready for work, start the client: java -cp client/lib/client-runtime-5.2-SNAPSHOT.jar:. Test terracotta://localhost:9000 (note that this example is assuming Unix delimiters)

The client should then print a line similar to this and exit with status 0: Connection established! com.terracotta.connection.TerracottaConnection@5d5eef3d

This proves that the client and server are able to start up and connect, without issue.