Getting Started

❗️

This is a legacy Apache Ignite documentation

The new documentation is hosted here: https://ignite.apache.org/docs/latest/

This page helps you to get started with Apache Ignite, set up the very first project and get the application working.

👍

Apache Ignite Essentials Series

Once you finished this getting started guide, we recommend you to watch the recordings of Apache Ignite Essentials webinars to gain a deeper understanding of how the technology works.

Prerequisites

Apache Ignite was officially tested on:

If you use Java version 9 or later, see Running Ignite with Java 9 or later for details.

Installing Apache Ignite

The easiest way to start with Apache Ignite is by using binary ZIP archives produced for every release:

• Download a ZIP archive with the latest version of Ignite.
• Unzip the package into a folder of your operating system.
• (Optional) Move the ignite-rest-http folder from {ignite}/libs/optional to {ignite}/libs to enable the Ignite REST library for Ignite Web Console that can be used for cluster management and monitoring needs.
• (Optional) Set the IGNITE_HOME environment variable or Windows PATH to point to the installation folder and make sure there is no trailing / (or \ for Windows) in the path. Do this only if you have issues running Apache Ignite on your machine.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="workDirectory" value="/path/to/work/directory"/>
    <!-- other properties -->
</bean>

IgniteConfiguration igniteCfg = new IgniteConfiguration();
igniteCfg.setWorkDirectory("/path/to/work/directory");

Starting Ignite Cluster

You can start an Ignite cluster node from the command line using the default configuration or by passing a custom configuration file. You can start as many nodes as you like and they will all automatically discover each other.

Go to the bin folder of the Ignite installation directory from the command shell:

cd {ignite}/bin/

cd {ignite}\bin\

Start an Ignite node with a custom configuration file passing it as a parameter to ignite.sh|bat like this:

./ignite.sh ../examples/config/example-ignite.xml

ignite.bat ..\examples\config\example-ignite.xml

You will see output similar to this one below:

[08:53:45] Ignite node started OK (id=7b30bc8e)
[08:53:45] Topology snapshot [ver=1, locNode=7b30bc8e, servers=1, clients=0, state=ACTIVE, CPUs=4, offheap=1.6GB, heap=2.0GB]

Open another tab from your command shell and run the same command again to add one more node to the cluster:

./ignite.sh ../examples/config/example-ignite.xml

ignite.bat ..\examples\config\example-ignite.xml

Check the output again paying attention to the Topology snapshot line. Now you have a cluster of two server nodes with more CPUs and RAM available cluster-wide:

[08:54:34] Ignite node started OK (id=3a30b7a4)
[08:54:34] Topology snapshot [ver=2, locNode=3a30b7a4, servers=2, clients=0, state=ACTIVE, CPUs=4, offheap=3.2GB, heap=4.0GB]

📘

Default Configuration

By default, ignite.sh|bat starts a node with the default configuration file located in config/default-config.xml.

Congratulations! You've just launched your first Ignite cluster.

Creating First Application

Once the cluster is started, it's time to create a HelloWorld example for Ignite. This time you will be using Maven that adds all required Ignite artifacts to your Java application.

Creating Maven Project

Create a new Maven project with your favorite IDE and add the following dependencies to the project’s pom.xml file.

<properties>
    <ignite.version>2.8.0</ignite.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.apache.ignite</groupId>
        <artifactId>ignite-core</artifactId>
        <version>${ignite.version}</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ignite</groupId>
        <artifactId>ignite-spring</artifactId>
        <version>${ignite.version}</version>
    </dependency>
</dependencies>

📘

Changing Ignite Version and Enabling Other Modules

Replace ignite.version parameters with your version of Ignite.

Add other Ignite Maven artifacts as dependencies if needed. For instance, you need to import ignite-indexing to enable Ignite SQL APIs and add ignite-ml for using the Ignite ML library.

Adding IgniteHelloWorld

Here is a sample IgniteHelloWord.java file that prints 'Hello World' and some other environment details on all the server nodes of the already started cluster. The sample shows how to prepare a cluster configuration with Java APIs, create a custom cache, load it with the data and execute a Java task on the server nodes in the map-reduce fashion.

public class IgniteHelloWorld {
    public static void main(String[] args) throws IgniteException {
        // Preparing IgniteConfiguration using Java APIs
        IgniteConfiguration cfg = new IgniteConfiguration();

        // The node will be started as a client node.
        cfg.setClientMode(true);

        // Classes of custom Java logic will be transferred over the wire from this app.
        cfg.setPeerClassLoadingEnabled(true);

        // Setting up an IP Finder to ensure the client can locate the servers.
        TcpDiscoveryMulticastIpFinder ipFinder = new TcpDiscoveryMulticastIpFinder();
        ipFinder.setAddresses(Collections.singletonList("127.0.0.1:47500..47509"));
        cfg.setDiscoverySpi(new TcpDiscoverySpi().setIpFinder(ipFinder));

        // Starting the node
        Ignite ignite = Ignition.start(cfg);

        // Create an IgniteCache and put some values in it.
        IgniteCache<Integer, String> cache = ignite.getOrCreateCache("myCache");
        cache.put(1, "Hello");
        cache.put(2, "World!");

        System.out.println(">> Created the cache and add the values.");

        // Executing custom Java compute task on server nodes.
        ignite.compute(ignite.cluster().forServers()).broadcast(new RemoteTask());

        System.out.println(">> Compute task is executed, check for output on the server nodes.");

        // Disconnect from the cluster.
        ignite.close();
    }

    /**
     * A compute tasks that prints out a node ID and some details about its OS and JRE.
     * Plus, the code shows how to access data stored in a cache from the compute task.
     */
    private static class RemoteTask implements IgniteRunnable {
        @IgniteInstanceResource
        Ignite ignite;

        @Override public void run() {
            System.out.println(">> Executing the compute task");

            System.out.println(
                "   Node ID: " + ignite.cluster().localNode().id() + "\n" +
                "   OS: " + System.getProperty("os.name") +
                "   JRE: " + System.getProperty("java.runtime.name"));

            IgniteCache<Integer, String> cache = ignite.cache("myCache");

            System.out.println(">> " + cache.get(1) + " " + cache.get(2));
        }
    }
}

Don’t forget to add imports to IgniteHelloWorld.java. It should be trivial as long as Maven and IDEs solve all of the dependencies.

You might also need to add these settings to your pom.xml if the IDE keeps using Java compiler from a version earlier than 1.8:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
    </plugins>
</build>

Running the Application

Compile and run IgniteHelloWorld.java. You will see 'Hello World!' and other environment details printed on all the server nodes.

Congratulations! You've just created your first Ignite application that connected and used resources of the cluster running in your local environment! Below are the next steps you might want to take.

Cluster Management and Monitoring

The easiest way to monitor the state of the cluster and control its behavior is with Apache Ignite tools such as Web Console and Ignite Visor Command Line.

Further Coding Examples

Keep learning Apache Ignite by studying the technical documentation and running code samples shipped withing the binary package. Create a Maven project from the examples located in your Ignite's installation directory under the {ignite}\examples paths.

📘

Examples in Github

If it's more convenient for you, the examples can be downloaded from the Ignite's Github repository: https://github.com/apache/ignite/tree/master/examples

Running Ignite with Java 11 and Later Versions

To run Ignite with Java 11 or later, perform the following steps:

1. Set the JAVA_HOME environment variable or Windows PATH to point to the Java installation directory.

2. Ignite uses proprietary SDK APIs that are not available by default. You need to pass specific flags to JVM to make these APIs available. If you use the start-up script ignite.sh (or ignite.bat for Windows), you do not need to do anything because these flags are already set up in the script. Otherwise, provide the following parameters to the JVM of your application:

3. TLSv1.3, which is available in Java 11, is not supported at the moment. Consider adding -Djdk.tls.client.protocols=TLSv1.2 if SSL between nodes is used.

4. Add the following VM options to your Java applications. That's not needed if you use Java thin clients or Ignite JDBC.

--add-exports=java.base/jdk.internal.misc=ALL-UNNAMED 
--add-exports=java.base/sun.nio.ch=ALL-UNNAMED 
--add-exports=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED 
--add-exports=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED
--add-exports=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED
--add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED
--illegal-access=permit