Edit

Application Deployment Options

Overview

Apache Ignite.NET consists of .NET assemblies and Java jar files. The .NET assemblies are referenced by your project and are copied to an output folder during the build automatically. The JAR files can be handled automatically or manually, depending on the approach. Ignite.NET discovers them via the IgniteHome or JvmClasspath settings.

This page introduces several most-commonly used deployment options of Ignite.NET nodes.

NuGet Deployment

Apache.Ignite NuGet package includes a lib folder with all the required jar files. This folder has the <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> build action, and is copied automatically to the output directory during the build or publish process.

Make sure IGNITE_HOME is not set globally. Normally you don’t need to set IGNITE_HOME with NuGet, except for ASP.NET deployments (see below).

To disable this default build action, add the <ExcludeAssets>build</ExcludeAssets> property to the corresponding <PackageReference> in your .csproj file. This can be useful for thin client use cases and custom deployments.

<Project Sdk="Microsoft.NET.Sdk">
    ...

    <ItemGroup>
      <PackageReference Include="Apache.Ignite" Version="2.9.1">
          <ExcludeAssets>build</ExcludeAssets>
      </PackageReference>
    </ItemGroup>

</Project>

Single File Deployment

Ignite.NET supports single file deployment that is available in .NET Core 3 / .NET 5+.

Use the IncludeAllContentForSelfExtract MSBuild property to include jar files into the single-file bundle, or ship them separately.
See Troubleshooting: DllNotFoundException for a workaround that is required on .NET 5 with some Ignite versions.

Publish command example:

dotnet publish --self-contained true -r linux-x64 -p:PublishSingleFile=true -p:IncludeAllContentForSelfExtract=true

Full Binary Package Deployment

Copy the whole Ignite distribution package along with your application
Set the IGNITE_HOME environment variable or IgniteConfiguration.IgniteHome setting to point to that folder

Custom Deployment

The JAR files are located in the libs folder of the binary distribution and NuGet package. The minimum set of jars for Ignite.NET is:

ignite-core-{VER}.jar
cache-api-1.0.0.jar
ignite-indexing folder (if SQL queries are used)
ignite-spring folder (if a Spring XML configuration is used)

Deploying JARs to a default location:

Copy the JAR files to the libs folder next to Apache.Ignite.Core.dll
Do not set the IgniteConfiguration.JvmClasspath, IgniteConfiguration.IgniteHome properties and IGNITE_HOME environment variable

Deploying jar files to an arbitrary location:

Copy the JAR files somewhere
Set the IgniteConfiguration.JvmClasspath property to a semicolon-separated string of paths for each jar file
Do not set the IGNITE_HOME environment variable and IgniteConfiguration.IgniteHome property

c:\ignite-jars\ignite-core-1.5.0.final.jar;c:\ignite-jars\cache-api-1.0.0.jar

ASP.NET Deployment

JvmClasspath or IgniteHome have to be explicitly set when using Ignite in a web environment (IIS and IIS Express), because DDL files are copied to temporary folders, and Ignite can not locate JAR files automatically.

You can set IgniteHome like this in ASP.NET environment:

Ignition.Start(new IgniteConfiguration
{
    IgniteHome = HttpContext.Current.Server.MapPath(@"~\bin\")
});

Alternatively, IGNITE_HOME can be set globally. Add this line at the top of the Application_Start method in Global.asax.cs:

Environment.SetEnvironmentVariable("IGNITE_HOME", HttpContext.Current.Server.MapPath(@"~\bin\"));

Finally, you can use the following method to populate JvmClasspath:

static string GetDefaultWebClasspath()
{
    var dir = HttpContext.Current.Server.MapPath(@"~\bin\libs");

    return string.Join(";", Directory.GetFiles(dir, "*.jar"));
}

IIS Application Pool Lifecycle, AppDomains, and Ignite.NET

There is a known problem with IIS. When a web application is restarted due to code changes or a manual restart, the application pool process remains alive, while AppDomain gets recycled.

Ignite.NET automatically stops when AppDomain is unloaded. However, a new domain may be started when old one is still unloading. So the node from the old domain can have an IgniteConfiguration.IgniteInstanceName conflict with a node from the new domain.

To fix this issue make sure to either assign a unique IgniteInstanceName, or set IgniteConfiguration.AutoGenerateIgniteInstanceName property to true.

var cfg = new IgniteConfiguration { AutoGenerateIgniteInstanceName = true };

<igniteConfiguration autoGenerateIgniteInstanceName="true">
  ...
</igniteConfiguration>

Refer to the following StackOverflow discussion for more details.

© 2024 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.