You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment/installing.adoc
+67-76Lines changed: 67 additions & 76 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,58 @@
1
1
[[deployment.installing]]
2
2
== Installing Spring Boot Applications
3
-
In addition to running Spring Boot applications by using `java -jar`, it is also possible to make fully executable applications for Unix systems.
4
-
A fully executable jar can be executed like any other executable binary or it can be <<deployment#deployment.installing.nix-services,registered with `init.d` or `systemd`>>.
5
-
This helps when installing and managing Spring Boot applications in common production environments.
3
+
In addition to running Spring Boot applications by using `java -jar` directly, it is also possible to run them as `systemd`, `init.d` or Windows services.
4
+
5
+
6
+
7
+
[[deployment.installing.system-d]]
8
+
=== Installation as a systemd Service
9
+
`systemd` is the successor of the System V init system and is now being used by many modern Linux distributions.
10
+
Spring Boot applications can be launched by using `systemd` '`service`' scripts.
11
+
12
+
Assuming that you have a Spring Boot application packaged as an uber jar in `/var/myapp`, to install it as a `systemd` service, create a script named `myapp.service` and place it in `/etc/systemd/system` directory.
IMPORTANT: Remember to change the `Description`, `User`, `Group`, `Environment` and `ExecStart` fields for your application.
36
+
37
+
NOTE: The `ExecStart` field does not declare the script action command, which means that the `run` command is used by default.
38
+
39
+
The user that runs the application, the PID file, and the console log file are managed by `systemd` itself and therefore must be configured by using appropriate fields in the '`service`' script.
40
+
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
41
+
42
+
To flag the application to start automatically on system boot, use the following command:
43
+
44
+
[source,shell,indent=0,subs="verbatim"]
45
+
----
46
+
$ systemctl enable myapp.service
47
+
----
48
+
49
+
Run `man systemctl` for more details.
50
+
51
+
52
+
53
+
[[deployment.installing.init-d]]
54
+
=== Installation as an init.d Service (System V)
55
+
To use your application as `init.d` service, configure its build to produce a <<deployment#deployment.installing, fully executable jar>>.
6
56
7
57
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
8
58
Currently, some tools do not accept this format, so you may not always be able to use this technique.
@@ -35,30 +85,11 @@ The following example shows the equivalent Gradle configuration:
35
85
}
36
86
----
37
87
38
-
You can then run your application by typing `./my-application.jar` (where `my-application` is the name of your artifact).
39
-
The directory containing the jar is used as your application's working directory.
40
-
41
-
88
+
It can then be symlinked to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands.
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
46
-
Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`.
47
-
48
-
49
-
50
-
[[deployment.installing.nix-services]]
51
-
=== Unix/Linux Services
52
-
Spring Boot application can be easily started as Unix/Linux services by using either `init.d` or `systemd`.
53
-
54
-
55
-
56
-
[[deployment.installing.nix-services.init-d]]
57
-
==== Installation as an init.d Service (System V)
58
-
If you configured Spring Boot's Maven or Gradle plugin to generate a <<deployment#deployment.installing, fully executable jar>>, and you do not use a custom `embeddedLaunchScript`, your application can be used as an `init.d` service.
59
-
To do so, symlink the jar to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands.
60
-
61
-
The script supports the following features:
90
+
The default launch script that is added to a fully executable jar supports most Linux distributions and is tested on CentOS and Ubuntu.
91
+
Other platforms, such as OS X and FreeBSD, require the use of a custom script.
92
+
The default scripts supports the following features:
62
93
63
94
* Starts the services as the user that owns the jar file
64
95
* Tracks the application's PID by using `/var/run/<appname>/<appname>.pid`
@@ -91,8 +122,8 @@ For example, on Debian, you could use the following command:
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service.
97
128
It is not intended to be an exhaustive list of everything that should be done to harden an application and the environment in which it runs.
98
129
@@ -130,7 +161,7 @@ One way to protect against this is to make it immutable by using `chattr`, as sh
130
161
131
162
This will prevent any user, including root, from modifying the jar.
132
163
133
-
If root is used to control the application's service and you <<deployment#deployment.installing.nix-services.script-customization.when-running.conf-file, use a `.conf` file>> to customize its startup, the `.conf` file is read and evaluated by the root user.
164
+
If root is used to control the application's service and you <<deployment#deployment.installing.init-d.script-customization.when-running.conf-file, use a `.conf` file>> to customize its startup, the `.conf` file is read and evaluated by the root user.
134
165
It should be secured accordingly.
135
166
Use `chmod` so that the file can only be read by the owner and use `chown` to make root the owner, as shown in the following example:
136
167
@@ -142,56 +173,15 @@ Use `chmod` so that the file can only be read by the owner and use `chown` to ma
142
173
143
174
144
175
145
-
[[deployment.installing.nix-services.system-d]]
146
-
==== Installation as a systemd Service
147
-
`systemd` is the successor of the System V init system and is now being used by many modern Linux distributions.
148
-
Although you can continue to use `init.d` scripts with `systemd`, it is also possible to launch Spring Boot applications by using `systemd` '`service`' scripts.
149
-
150
-
Assuming that you have a Spring Boot application installed in `/var/myapp`, to install a Spring Boot application as a `systemd` service, create a script named `myapp.service` and place it in `/etc/systemd/system` directory.
151
-
The following script offers an example:
152
-
153
-
[indent=0]
154
-
----
155
-
[Unit]
156
-
Description=myapp
157
-
After=syslog.target
158
-
159
-
[Service]
160
-
User=myapp
161
-
ExecStart=/var/myapp/myapp.jar
162
-
SuccessExitStatus=143
163
-
164
-
[Install]
165
-
WantedBy=multi-user.target
166
-
----
167
-
168
-
IMPORTANT: Remember to change the `Description`, `User`, and `ExecStart` fields for your application.
169
-
170
-
NOTE: The `ExecStart` field does not declare the script action command, which means that the `run` command is used by default.
171
-
172
-
Note that, unlike when running as an `init.d` service, the user that runs the application, the PID file, and the console log file are managed by `systemd` itself and therefore must be configured by using appropriate fields in the '`service`' script.
173
-
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
174
-
175
-
To flag the application to start automatically on system boot, use the following command:
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment#deployment.installing.nix-services.script-customization.when-running.conf-file, config file>>.
294
+
For items of the script that need to be customized _after_ the jar has been written, you can use environment variables or a <<deployment#deployment.installing.init-d.script-customization.when-running.conf-file, config file>>.
305
295
306
296
The following environment properties are supported with the default script:
307
297
@@ -364,7 +354,8 @@ See the https://www.freedesktop.org/software/systemd/man/systemd.service.html[se
With the exception of `JARFILE` and `APP_NAME`, the settings listed in the preceding section can be configured by using a `.conf` file.
369
360
The file is expected to be next to the jar file and have the same name but suffixed with `.conf` rather than `.jar`.
370
361
For example, a jar named `/var/myapp/myapp.jar` uses the configuration file named `/var/myapp/myapp.conf`, as shown in the following example:
@@ -378,7 +369,7 @@ For example, a jar named `/var/myapp/myapp.jar` uses the configuration file name
378
369
379
370
TIP: If you do not like having the config file next to the jar file, you can set a `CONF_FOLDER` environment variable to customize the location of the config file.
380
371
381
-
To learn about securing this file appropriately, see <<deployment#deployment.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
372
+
To learn about securing this file appropriately, see <<deployment#deployment.installing.init-d.securing,the guidelines for securing an init.d service>>.
0 commit comments