// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= 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>` https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#controlling-dependency-assets[property] to the corresponding `<PackageReference>` in your `.csproj` file.
This can be useful for thin client use cases and custom deployments.

[tabs]
--
tab:MyApp.csproj[]
[source,xml]
----
<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 link:https://docs.microsoft.com/en-us/dotnet/core/deploying/single-file[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 xref:net-troubleshooting.adoc#libcoreclr-not-found[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 https://ignite.apache.org/download.cgi#binaries[whole Ignite distribution package, window=_blank] 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

[tabs]
--
tab:IgniteConfiguration.JvmClasspath Example[]
[source,shell]
----
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:

[tabs]
--
tab:C#[]
[source,csharp]
----
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`:

[tabs]
--
tab:C#[]
[source,csharp]
----
Environment.SetEnvironmentVariable("IGNITE_HOME", HttpContext.Current.Server.MapPath(@"~\bin\"));
----
--

Finally, you can use the following method to populate `JvmClasspath`:
[tabs]
--
tab:C#[]
[source,csharp]
----
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`.

[tabs]
--
tab:Use in C#[]
[source,csharp]
----
var cfg = new IgniteConfiguration { AutoGenerateIgniteInstanceName = true };
----
tab:web.config[]
[source,xml]
----
<igniteConfiguration autoGenerateIgniteInstanceName="true">
  ...
</igniteConfiguration>
----
--

Refer to the http://stackoverflow.com/questions/42961879/how-do-i-retrieve-a-started-ignite-instance-when-a-website-restart-occurs-in-iis/[following StackOverflow discussion, window=_blank]
for more details.