[MDEPOY-250] document network issues workaround found by PLC4X
authorHervé Boutemy <hboutemy@apache.org>
Sun, 20 Jan 2019 16:26:38 +0000 (17:26 +0100)
committerHervé Boutemy <hboutemy@apache.org>
Sun, 20 Jan 2019 16:26:38 +0000 (17:26 +0100)
src/site/apt/examples/deploy-network-issues.apt [new file with mode: 0644]
src/site/apt/index.apt.vm
src/site/apt/project-deployment.apt

diff --git a/src/site/apt/examples/deploy-network-issues.apt b/src/site/apt/examples/deploy-network-issues.apt
new file mode 100644 (file)
index 0000000..059f4eb
--- /dev/null
@@ -0,0 +1,123 @@
+ ------
+ Deploying With Network Issues
+ ------
+ Hervé Boutemy
+ ------
+ 2019-01-20
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Deploying With Network Issues
+
+ Sometimes, network quality from building machine to the remote repository is not perfect.
+ Of course, improving the network would be the best solution, but it is not always possible.
+
+ There are a few strategies to work around the network issue.
+
+* Configuring Multiple Tries
+
+ Deploy plugin provides {{{../deploy-mojo.html#retryFailedDeploymentCount}<<<retryFailedDeploymentCount>>> parameter}}
+ to retry deployment multiple times before giving up and returning a failure for the <<<deploy>>> goal: 
+
++----+
+<project>
+  [...]
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-deploy-plugin</artifactId>
+        <configuration>
+          <retryFailedDeploymentCount>3</retryFailedDeploymentCount>
+        <configuration>
+      </plugin>
+    </plugins>
+  </build>
+  [...]
+</project>
++----+
+
+* Deploying to a Local Staging Directory
+
+ When the network is really not consistent, a deeper strategy is to deploy in 2 steps:
+
+ 1. <<<deploy>>> to a local <<<file:./target/staging-deploy>>> directory during the build,
+
+ 2. then copy from the local area to the target remote repository, retrying as much as necessary.
+
+ []
+
+** Deploying to a Local Directory
+
+ Deploying to a local directory can be done from command line, without changing POM, using
+ {{{../deploy-mojo.html#altDeploymentRepository}<<<altDeploymentRepository>>> parameter}}:
++----+
+mvn deploy -DaltDeploymentRepository=local::file:./target/staging-deploy
++----+  
+
+ Notice: with maven-deploy-plugin 2.x, the parameter format was <<<local::default::file:./target/staging-deploy>>>
+
+ Of course, if you want can configure the repository in your <<<pom.xml>>> if you want to go from a temporary strategy
+ to the general strategy.
+** Copying from Local Directory to Target Remote Repository
+
+ <<<wagon-maven-plugin>>>'s {{{http://www.mojohaus.org/wagon-maven-plugin/merge-maven-repos-mojo.html}<<<merge-maven-repos>>> goal}}
+ provides a mechanism to copy from one remote repository to the other, while merging repository metadata.
+ <<<wagon-maven-plugin>>>'s {{{http://www.mojohaus.org/wagon-maven-plugin/upload-mojo.html}<<<upload>>> goal}}
+ will do the same without taking care of repository metadata: use it if you have an empty repository as target,
+ like a staging repository provided by a repository manager.
+ It can be invoked fully from command line (renaming <<<-Dwagon.>>> with <<<wagon.targetId>>> when
+ {{{https://github.com/mojohaus/wagon-maven-plugin/pull/26}2.0.1 will be released}}):
+
++----+
+mvn org.codehaus.mojo:wagon-maven-plugin:2.0.0:merge-maven-repos \
+  -Dwagon.source=file:./target/staging-deploy \
+  -Dwagon.target=https://... \
+  -Dwagon.=id
++----+
+
+ or more simply with <<<mvn wagon:merge-maven-repos>>> with configuration in <<<pom.xml>>>:
+
++----+
+<project>
+  [...]
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>wagon-maven-plugin</artifactId>
+        <version>2.0.0</version>
+        <configuration>
+          <source>file:./target/staging-deploy</source>
+          <target>https://...</target>
+          <targetId>id</targetId>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+  [...]
+</project>
++----+
index c5e814e..c91364d 100644 (file)
@@ -114,6 +114,8 @@ ${project.name}
 
   * {{{./examples/deploy-ssh-external.html}Deployment with external SSH}}
 
+  * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}}
+
   []
 
   <File Deployment:>
index 39d3390..e74a029 100644 (file)
@@ -34,4 +34,6 @@ Project Deployment
 
   * {{{./examples/deploy-ssh-external.html}Deployment with external SSH}}
 
+  * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}}
+
   []
\ No newline at end of file