apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Installing Using Docker
16

17
== Considerations
18

19
*In-memory vs. Persistent Cluster*::
20
+
21
--
22
When deploying a persistent Ignite cluster, you should always mount a persistent volume or local directory.
23
If you do not use a persistent volume, Ignite will store the data in the container's file system.
24
It means that the data will be erased when you remove the container. To save the data in a permanent location, <<Running Persistent Cluster,mount a persistent volume>>.
25
--
26

27
*Networking*::
28
+
29
--
30
By default, Ignite Docker image exposes the following ports: 11211, 47100, 47500, 49112.
31
You can expose more ports as needed by adding `-p <port>` to the `docker run` command.
32
For example, to connect a thin client to the node running inside a docker container, open port 10800:
33

34
[source, shell]
35
----
36
docker run -d -p 10800:10800 apacheignite/ignite
37
----
38
--
39

40
== Downloading Ignite Docker Image
41

42
Assuming that you already have Docker installed on your machine, you can pull
43
and run the Ignite Docker image using the following commands.
44

45
Open a command shell and use the following command to pull the Ignite Docker image.
46
[source,shell]
47
----
48
# Pull latest version
49
sudo docker pull apacheignite/ignite
50
----
51

52
By default, the latest version is downloaded, but you can download a specific version too.
53
[source,shell,subs="attributes,specialchars"]
54
----
55
# Pull a specific Ignite version
56
sudo docker pull apacheignite/ignite:{version}
57
----
58

59
== Running In-Memory Cluster
60

61
Run Ignite in a docker container using the `docker run` command.
62

63
[source,shell]
64
----
65
# Run the latest version
66
sudo docker run -d apacheignite/ignite
67
----
68

69
This command will launch a single Ignite node.
70

71
To run a specific version of Ignite, use the following command:
72

73
[source,shell,subs="attributes,specialchars"]
74
----
75
# Run a specific Ignite version
76
sudo docker run -d apacheignite/ignite:{version}
77
----
78

79
== Running Persistent Cluster
80

81
If you use link:persistence/native-persistence[Native Persistence], Ignite stores the user data under the default work directory (`{IGNITE_HOME}/work`) in the file system of the container. This directory will be erased if you restart the docker container. To avoid this, you can:
82

83
- Use a persistent volume to store the data; or
84
- Mount a local directory
85

86
These two options are described in the following sections.
87

88
=== Using Persistent Volume
89

90

91
To create a persistent volume, run the following command:
92

93
[source, shell]
94
----
95
sudo docker volume create persistence-volume
96
----
97

98
We will mount this volume to a specific directory when running the Ignite docker image. This directory will have to be passed to Ignite. This can be done in two ways:
99

100
- Using the `IGNITE_WORK_DIR` system property
101
- In the node configuration file
102

103
The following command launches the Ignite Docker image and passes the work directory to Ignite via the system property:
104

105

106
[source,shell]
107
----
108
docker run -d \
109
  -v storage-volume:/storage \
110
  -e IGNITE_WORK_DIR=/storage \
111
  apacheignite/ignite
112
----
113

114
=== Using Local Directory
115

116
Instead of creating a volume, you can mount a local directory to the container in which the Ignite image is running and use this directory to store persistent data.
117
When restarting the container with the same command, Ignite will load the data from the directory.
118

119

120
[source, shell]
121
----
122
mkdir work_dir
123

124
docker run -d \
125
  -v ${PWD}/work_dir:/storage \
126
  -e IGNITE_WORK_DIR=/storage \
127
  apacheignite/ignite
128
----
129

130
The `-v` option mounts a local directory under the `/storage` path in the container.
131
The `-e IGNITE_WORK_DIR=/storage` option tells Ignite to use this folder as the work directory.
132

133

134
== Providing Configuration File
135
When you run the image, it starts a node with the default configuration file.
136
You can pass a custom configuration file by using the `CONFIG_URI` environment variable:
137

138
[source, shell]
139
----
140
docker run -d \
141
  -e CONFIG_URI=http://myserver/config.xml  \
142
  apacheignite/ignite
143
----
144

145
You can also use a file from your local file system.
146
You need to mount the file first under a specific path inside the container by using the `-v` option.
147
Then, use this path in the `CONFIG_URI` option:
148

149
[source, shell]
150
----
151
docker run -d \
152
  -v /local/dir/config.xml:/config-file.xml \
153
  -e CONFIG_URI=/config-file.xml \
154
  apacheignite/ignite
155
----
156

157
== Deploying User Libraries
158

159
When starting, a node adds all libraries found in the `{IGNITE_HOME}/libs` directory to the classpath (ignoring the "optional" directory).
160
If you want to deploy user libraries, you can mount a directory from your local machine to a path in the `/opt/ignite/apache-ignite/libs/` in the container by using the `-v` option.
161

162
The following command mounts a directory on your machine to `libs/user_libs` in the container.
163
All files located in the directory are added to the classpath of the node.
164

165
[source, shell]
166
----
167
docker run -v /local_path/to/dir_with_libs/:/opt/ignite/apache-ignite/libs/user_libs apacheignite/ignite
168
----
169

170
Another option is to use the `EXTERNAL_LIBS` variable if your libraries are available via an URL.
171

172
[source, shell]
173
----
174
docker run -e "EXTERNAL_LIBS=http://url_to_your_jar" apacheignite/ignite
175
----
176

177

178
== Enabling Modules
179

180
To enable specific link:setup#enabling-modules[modules], specify their names in the "OPTION_LIBS" system variable as follows:
181

182
[source, shell]
183
----
184
sudo docker run -d \
185
  -e "OPTION_LIBS=ignite-rest-http" \
186
  apacheignite/ignite
187
----
188

189
By default, the Ignite Docker image starts with the following modules enabled:
190

191
- ignite-log4j2,
192
- ignite-spring,
193
- ignite-indexing.
194

195
== Environment Variables
196

197
The following parameters can be passed as environment variables in the docker container:
198

199
[cols="1,2,1", options="header"]
200
|===
201
| Parameter Name |Description |Default
202
| `CONFIG_URI` | URL to the Ignite configuration file (can also be relative to the META-INF folder on the class path).
203
The downloaded config file is saved to ./ignite-config.xml | N/A
204

205
| `OPTION_LIBS` | A list of link:setup#enabling-modules[modules] that will be enabled for the node. | ignite-log4j2, ignite-spring, ignite-indexing
206

207
| `JVM_OPTS` | JVM arguments passed to the Ignite instance.| N/A
208

209
| `EXTERNAL_LIBS` | A list of URL's to external libraries. Refer to <<Deploying User Libraries>>.| N/A
210

211
|===
212

213