mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-07-15 01:07:30 +08:00
Merge branch '2.7.x' into 3.0.x
Closes gh-38115
This commit is contained in:
Andy Wilkinson
commit
9aae29b60b
@ -1017,3 +1017,14 @@ actuator.tracing.custom=actuator.http-exchanges.custom
|
||||
# gh-35917
|
||||
howto.actuator.sanitize-sensitive-values=actuator.endpoints.sanitization
|
||||
howto.actuator.sanitize-sensitive-values.customizing-sanitization=howto.actuator.customizing-sanitization
|
||||
|
||||
# gh-28453
|
||||
deployment.installing.supported-operating-systems=deployment.installing
|
||||
deployment.installing.nix-services=deployment.installing
|
||||
deployment.installing.nix-services.init-d=deployment.installing.init-d
|
||||
deployment.installing.nix-services.init-d.securing=deployment.installing.init-d.securing
|
||||
deployment.installing.nix-services.system-d=deployment.installing.system-d
|
||||
deployment.installing.nix-services.script-customization=deployment.installing.init-d.script-customization
|
||||
deployment.installing.nix-services.script-customization.when-written=deployment.installing.init-d.script-customization.when-written
|
||||
deployment.installing.nix-services.script-customization.when-running=deployment.installing.init-d.script-customization.when-running
|
||||
deployment.installing.nix-services.script-customization.when-running.conf-file=deployment.installing.init-d.script-customization.when-running.conf-file
|
||||
|
||||
@ -1,8 +1,58 @@
|
||||
[[deployment.installing]]
|
||||
== Installing Spring Boot Applications
|
||||
In addition to running Spring Boot applications by using `java -jar`, it is also possible to make fully executable applications for Unix systems.
|
||||
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`>>.
|
||||
This helps when installing and managing Spring Boot applications in common production environments.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.system-d]]
|
||||
=== Installation as a systemd Service
|
||||
`systemd` is the successor of the System V init system and is now being used by many modern Linux distributions.
|
||||
Spring Boot applications can be launched by using `systemd` '`service`' scripts.
|
||||
|
||||
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.
|
||||
The following script offers an example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
[Unit]
|
||||
Description=myapp
|
||||
After=syslog.target network.target
|
||||
|
||||
[Service]
|
||||
User=myapp
|
||||
Group=myapp
|
||||
|
||||
Environment="JAVA_HOME=/path/to/java/home"
|
||||
|
||||
ExecStart=${JAVA_HOME}/bin/java -jar /var/myapp/myapp.jar
|
||||
ExecStop=/bin/kill -15 $MAINPID
|
||||
SuccessExitStatus=143
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
----
|
||||
|
||||
IMPORTANT: Remember to change the `Description`, `User`, `Group`, `Environment` and `ExecStart` fields for your application.
|
||||
|
||||
NOTE: The `ExecStart` field does not declare the script action command, which means that the `run` command is used by default.
|
||||
|
||||
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.
|
||||
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
To flag the application to start automatically on system boot, use the following command:
|
||||
|
||||
[source,shell,indent=0,subs="verbatim"]
|
||||
----
|
||||
$ systemctl enable myapp.service
|
||||
----
|
||||
|
||||
Run `man systemctl` for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.init-d]]
|
||||
=== Installation as an init.d Service (System V)
|
||||
To use your application as `init.d` service, configure its build to produce a <<deployment#deployment.installing, fully executable jar>>.
|
||||
|
||||
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
|
||||
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:
|
||||
}
|
||||
----
|
||||
|
||||
You can then run your application by typing `./my-application.jar` (where `my-application` is the name of your artifact).
|
||||
The directory containing the jar is used as your application's working directory.
|
||||
It can then be symlinked to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.supported-operating-systems]]
|
||||
=== Supported Operating Systems
|
||||
The default script supports most Linux distributions and is tested on CentOS and Ubuntu.
|
||||
Other platforms, such as OS X and FreeBSD, require the use of a custom `embeddedLaunchScript`.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services]]
|
||||
=== Unix/Linux Services
|
||||
Spring Boot application can be easily started as Unix/Linux services by using either `init.d` or `systemd`.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.init-d]]
|
||||
==== Installation as an init.d Service (System V)
|
||||
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.
|
||||
To do so, symlink the jar to `init.d` to support the standard `start`, `stop`, `restart`, and `status` commands.
|
||||
|
||||
The script supports the following features:
|
||||
The default launch script that is added to a fully executable jar supports most Linux distributions and is tested on CentOS and Ubuntu.
|
||||
Other platforms, such as OS X and FreeBSD, require the use of a custom script.
|
||||
The default scripts supports the following features:
|
||||
|
||||
* Starts the services as the user that owns the jar file
|
||||
* 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:
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.init-d.securing]]
|
||||
===== Securing an init.d Service
|
||||
[[deployment.installing.init-d.securing]]
|
||||
==== Securing an init.d Service
|
||||
NOTE: The following is a set of guidelines on how to secure a Spring Boot application that runs as an init.d service.
|
||||
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.
|
||||
|
||||
@ -130,7 +161,7 @@ One way to protect against this is to make it immutable by using `chattr`, as sh
|
||||
|
||||
This will prevent any user, including root, from modifying the jar.
|
||||
|
||||
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.
|
||||
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.
|
||||
It should be secured accordingly.
|
||||
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:
|
||||
|
||||
@ -142,48 +173,7 @@ Use `chmod` so that the file can only be read by the owner and use `chown` to ma
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.system-d]]
|
||||
==== Installation as a systemd Service
|
||||
`systemd` is the successor of the System V init system and is now being used by many modern Linux distributions.
|
||||
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.
|
||||
|
||||
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.
|
||||
The following script offers an example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
[Unit]
|
||||
Description=myapp
|
||||
After=syslog.target
|
||||
|
||||
[Service]
|
||||
User=myapp
|
||||
ExecStart=/var/myapp/myapp.jar
|
||||
SuccessExitStatus=143
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
----
|
||||
|
||||
IMPORTANT: Remember to change the `Description`, `User`, and `ExecStart` fields for your application.
|
||||
|
||||
NOTE: The `ExecStart` field does not declare the script action command, which means that the `run` command is used by default.
|
||||
|
||||
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.
|
||||
Consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
|
||||
|
||||
To flag the application to start automatically on system boot, use the following command:
|
||||
|
||||
[source,shell,indent=0,subs="verbatim"]
|
||||
----
|
||||
$ systemctl enable myapp.service
|
||||
----
|
||||
|
||||
Run `man systemctl` for more details.
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization]]
|
||||
[[deployment.installing.init-d.script-customization]]
|
||||
==== Customizing the Startup Script
|
||||
The default embedded startup script written by the Maven or Gradle plugin can be customized in a number of ways.
|
||||
For most people, using the default script along with a few customizations is usually enough.
|
||||
@ -191,7 +181,7 @@ If you find you cannot customize something that you need to, use the `embeddedLa
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-written]]
|
||||
[[deployment.installing.init-d.script-customization.when-written]]
|
||||
===== Customizing the Start Script When It Is Written
|
||||
It often makes sense to customize elements of the start script as it is written into the jar file.
|
||||
For example, init.d scripts can provide a "`description`".
|
||||
@ -299,9 +289,9 @@ The following property substitutions are supported with the default script:
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-running]]
|
||||
[[deployment.installing.init-d.script-customization.when-running]]
|
||||
===== Customizing a Script When It Runs
|
||||
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>>.
|
||||
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>>.
|
||||
|
||||
The following environment properties are supported with the default script:
|
||||
|
||||
@ -364,7 +354,8 @@ See the https://www.freedesktop.org/software/systemd/man/systemd.service.html[se
|
||||
|
||||
|
||||
|
||||
[[deployment.installing.nix-services.script-customization.when-running.conf-file]]
|
||||
[[deployment.installing.init-d.script-customization.when-running.conf-file]]
|
||||
====== Using a Conf Gile
|
||||
With the exception of `JARFILE` and `APP_NAME`, the settings listed in the preceding section can be configured by using a `.conf` file.
|
||||
The file is expected to be next to the jar file and have the same name but suffixed with `.conf` rather than `.jar`.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
To learn about securing this file appropriately, see <<deployment#deployment.installing.nix-services.init-d.securing,the guidelines for securing an init.d service>>.
|
||||
To learn about securing this file appropriately, see <<deployment#deployment.installing.init-d.securing,the guidelines for securing an init.d service>>.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -2,6 +2,6 @@
|
||||
== Advanced Topics
|
||||
Finally, we have a few topics for more advanced users:
|
||||
|
||||
* *Spring Boot Applications Deployment:* <<deployment#deployment.cloud, Cloud Deployment>> | <<deployment#deployment.installing.nix-services, OS Service>>
|
||||
* *Spring Boot Applications Deployment:* <<deployment#deployment.cloud, Cloud Deployment>> | <<deployment#deployment.installing, OS Service>>
|
||||
* *Build tool plugins:* <<build-tool-plugins#build-tool-plugins.maven, Maven>> | <<build-tool-plugins#build-tool-plugins.gradle, Gradle>>
|
||||
* *Appendix:* <<application-properties#appendix.application-properties,Application Properties>> | <<configuration-metadata#appendix.configuration-metadata,Configuration Metadata>> | <<auto-configuration-classes#appendix.auto-configuration-classes,Auto-configuration Classes>> | <<test-auto-configuration#appendix.test-auto-configuration,Test Auto-configuration Annotations>> | <<executable-jar#appendix.executable-jar,Executable Jars>> | <<dependency-versions#appendix.dependency-versions,Dependency Versions>>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user