// 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.
= Getting Started Guide

This guide provides essential details on how to start working with Ignite 3.0 Alpha 4 by using the Ignite CLI tool, including the following information:

* How to download and install the tool.
* How to use the Ignite CLI tool to manage nodes.
* How to run built-in examples.
* Additional information regarding the use of the tool.

== Prerequisites


Ignite 3.0 Alpha 4 was officially tested on:

include::../includes/prereqs.adoc[]


== Installing Ignite CLI Tool

To download and install the Ignite CLI Tool, follow the steps below:

. Download the archive with the Ignite CLI tool:
+
[tabs]
--
tab:Unix[]
[source,shell]
----
curl -L "https://www.apache.org/dyn/mirrors/mirrors.cgi?action=download&filename=ignite/3.0.0-alpha4/apache-ignite-3.0.0-alpha4.zip" -o apache-ignite-3.0.0-alpha4.zip
----

tab:Windows (PowerShell)[]
[source,shell]
----
include::../includes/ignite-cli-download-windows.adoc[tag=command,indent=0]
----

tab:Windows (CMD)[]
[source,shell]
----
include::../includes/ignite-cli-download-windows.adoc[tag=command,indent=0]
----
--

. Unpack the archive:
+
[tabs]
--
tab:Unix[]
[source,shell]
----
unzip apache-ignite-3.0.0-alpha4.zip && cd apache-ignite-3.0.0-alpha4
----

tab:Windows (PowerShell)[]
[source,shell]
----
Expand-Archive apache-ignite-3.0.0-alpha4.zip -DestinationPath . ; cd apache-ignite-3.0.0-alpha4
----

tab:Windows (CMD)[]
[source,shell]
----
tar -xf apache-ignite-3.0.0-alpha4.zip & cd apache-ignite-3.0.0-alpha4
----
--

. Add your installation directory to the PATH environment variable:
+
[tabs]
--
tab:Unix[]
[source,shell]
----
echo 'export PATH="'`pwd`':$PATH"' >> ~/.bash_profile && source ~/.bash_profile
----

tab:Windows (PowerShell)[]
[source,shell]
----
$ENV:PATH += ";."
----

tab:Windows (CMD)[]
[source,text]
----
set PATH=%cd%;%PATH%
----
--

NOTE: On Windows, this latter change is not permanent and only affects the current terminal session. If you want the
`ignite` command to be available after terminal or system restart, use the `System Properties` dialog to
permanently update the `PATH` environment variable by adding a full path to the Ignite installation directory.

== Using Ignite CLI Tool

Ignite CLI is a single entry point for all the Ignite operations. You can perform the following actions with it:

* Manage existing nodes.
* Install new nodes.
* Update old nodes to new versions.
* Install or remove optional modules.

Let's use some of the \<<Ignite CLI Tool Commands>>.

. Use the command below to see the full list:
+
[source, shell]
----
ignite
----

. Pass the `--help` parameter to the previous command to get its detailed description:
+
[source, shell]
----
ignite init --help
----

== Installing Ignite Artifacts and Dependencies

Ignite CLI allows to install Ignite modules and 3rd party Maven dependencies.

WARNING:
----
If you have installed one of the Ignite 3 Alpha releases before, please remove the `~/.ignitecfg` file before proceeding. This is a temporary step, the procedure will be improved in the future releases.
----

. To start an Ignite 3.0 Alpha 4 cluster, you need to install Ignite core artifacts first:
+
[source, shell]
----
ignite init
----

. Use the `module add` command to download Guava from Maven and add it to the Ignite classpath:
+
[source, shell]
----
ignite module add mvn:com.google.guava:guava:23.0
----

. Confirm the library is added to the Ignite dependencies list:
+
[source, shell]
----
ignite module list
----

== Starting a Node

This section explains how to start a node, how to stop, and perform other basic operations with it.

. Start a cluster node setting `my-first-node` as a node unique identifier:
+
[source, shell]
----
ignite node start --config=examples/config/ignite-config.json my-first-node
----

. Confirm the node is started and running:
+
[source, shell]
----
ignite node list
----
+
This command also displays the path to the log file.

. To view the log, use the log file path from the previous step result. To open the log file, use any suitable approach.
For example, use the `cat` command on a Unix operating system.

== Built-in Examples

Ignite 3.0 Alpha 4 comes with examples that are configured as a separate Maven project located in the `examples` folder.

The project includes the following examples:

* `RecordViewExample` demonstrates the usage of the `org.apache.ignite.table.RecordView` API to create a table. It also shows how to get data from a table, or insert a line into a table.
* `KeyValueViewExample` - demonstrates the usage of the `org.apache.ignite.table.KeyValueView` API to insert a line into a table.
* `SqlJdbcExample` - demonstrates the usage of the Apache Ignite JDBC driver.
* `RebalanceExample` - demonstrates the data rebalancing process.

To run the `RebalanceExample`, refer to its link:https://github.com/apache/ignite-3/blob/3.0.0-alpha4/examples/src/main/java/org/apache/ignite/example/rebalance/RebalanceExample.java[JavaDoc,window=_blank] for instructions.

To run any other example, perform the following steps:

. Import the examples project into you IDE.

. Start a server node using the CLI tool:
+
[source, shell script]
----
ignite node start --config=$IGNITE_HOME/examples/config/ignite-config.json my-first-node
----

. Run the preferred example in the IDE.


== Stopping the Cluster

To stop the node, use the command below passing `my-first-node` as a node unique identifier:
[source, shell]
----
ignite node stop my-first-node
----


== Next Steps

From here, you may want to:

* Check out the link:ignite-cli-tool[Ignite CLI Tool] page for more detail on supported commands.

//== Apache Ignite Configuration
//
//Apache Ignite uses HOCON configuration format.
//For more detail, please see the link:https://github.com/lightbend/config/blob/master/HOCON.md[HOCON documentation,window=_blank].






