From ab33bc7deb9b9744382745887a61f4efde9bd2d0 Mon Sep 17 00:00:00 2001
From: Sergei Petunin <petunin@crxmarkets.com>
Date: Sun, 4 Aug 2019 16:46:21 +0200
Subject: [PATCH] Expand documentation on remote devtools

See gh-17780
---
 .../src/main/asciidoc/using-spring-boot.adoc  | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
index 95b9a8bb57..cba8d992c1 100644
--- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
+++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
@@ -1139,6 +1139,66 @@ remote updates and restarts are much quicker than a full rebuild and deploy cycl
 NOTE: Files are only monitored when the remote client is running. If you change a file
 before starting the remote client, it is not pushed to the remote server.
 
+[[configuring-file-system-watcher]]
+==== Configuring File System Watcher
+{sc-spring-boot-devtools}/filewatch/FileSystemWatcher.{sc-ext}[FileSystemWatcher] works
+by polling the class changes with a certain time interval, and then waiting for a
+predefined quiet period to make sure no more changes are coming from the compiler. The
+changes are then being uploaded to the remote application. On a slower development
+environment, it may happen that the quiet period is not enough, and the changes in the
+classes appear to be split into two batches. The server is then restarted after the first
+batch of class changes is uploaded, but the second batch can’t immediately be sent to the
+application, since the server is restarting.
+
+This is typically manifested by a warning in the `RemoteSpringApplication` logs about
+failing to upload some of the classes, and a consequent retry. But it may also lead to the
+application code inconsistency and failure to restart after the first batch of changes is
+uploaded.
+
+If you observe such problems constantly, try increasing the
+`spring.devtools.restart.poll-interval` and `spring.devtools.restart.quiet-period`
+parameters to the values that fit your development environment:
+
+[source,properties,indent=0]
+----
+	spring.devtools.restart.poll-interval=2s
+	spring.devtools.restart.quiet-period=1s
+----
+
+The monitored classpath folders are now being swept every 2 seconds, and a 1 second quiet
+period is maintained to make sure no additional class changes are coming.
+
+[[security-configuration-for-devtools-remote]]
+==== Security Configuration for Devtools Remote
+If you use security configuration on the server, you may observe HTTP error 401 or 403 in
+the logs of the `RemoteSpringApplication`:
+
+[indent=0,subs="attributes"]
+----
+	Exception in thread "File Watcher" java.lang.IllegalStateException: Unexpected 401 UNAUTHORIZED response uploading class files
+----
+
+The URL for class uploading should be exempted both from the web security and from the
+csrf filter. Here’s an example `WebSecurityConfigurerAdapter` configuration that uses
+HTTP Basic Auth to secure all URLs except the default one used by devtools for class
+uploading:
+
+[source,java,indent=0]
+----
+@Configuration
+public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
+
+	@Override
+	protected void configure(HttpSecurity http) throws Exception {
+		http.authorizeRequests().antMatchers("/.~~spring-boot!~/restart").anonymous()
+			.and().csrf().ignoringAntMatchers("/.~~spring-boot!~/restart")
+			.and().authorizeRequests().anyRequest().authenticated()
+			.and().httpBasic();
+	}
+
+}
+----
+
 
 
 [[using-boot-packaging-for-production]]