Upload a website over FTP using Maven

We are in the erea of static documentation websites. Indeed you can create a docker image with your website and run it but it is quite overkill for a documentation website, in particular static. A plain old FTP server works well. There are tons of ways to upload a directory with your static website to a FTP server but did you know Maven can handle that? Let see that.

The very interesting part using maven is that the website handling is fully part of your project:

1. Generation of the content (living doc),
2. Website generation (using JBake, Antora, a custom script or so),
3. Website upload/deployment

The first step to enable FTP deployment through maven is to add wagon-ftp extension in your pom as an extension under build tag:

<project>
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-ftp</artifactId>
        <version>3.4.2</version>
      </extension>
    </extensions>
  </build>
</project>

Then add wagon maven plugin to your plugins - note that you can put it in a profile to avoid to run it each time:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>wagon-maven-plugin</artifactId> <!-- 1 -->
  <version>2.0.0</version>
  <executions>
    <execution>
      <id>upload-doc</id>
      <phase>none</phase> <!-- 2 -->
      <goals>
        <goal>upload</goal>
      </goals>
      <configuration>
        <!-- 3 -->
        <fromDir>${project.build.directory}/${project.build.finalName}</fromDir>
        <includes>**</includes>

        <!-- 4 -->
        <url>ftp://myserver.com</url>
        <toDir>/public_html</toDir>

        <!-- 5 -->
        <serverId>ftp://myserver.com</serverId>
      </configuration>
    </execution>
  </executions>
</plugin>

1. Define the plugin,
2. You can bind it to a phase to automatically run the plugin or not (set phase to none). If not bound you must execute mvn wagon:upload@upload-doc to run this execution manually,
3. Define where the files are read from and filter them (here we include everything since we assume we staged the website to upload),
4. Define where to upload the website to (host and subdir), note tht it can be neat to use a property for this url to override it (which would enable a staging environment),
5. Define the server id which will be used from your settings.xml to get the username/password to use to connect to your FTP server and upload the files.

Once this configuration done, you just miss the ~/.m2/settings.xml server matching the configured serverId (to retrieve credentials):

<settings>
  <servers>
    <server>
      <id>ftp://myserver.com</id>
      <username>myuser</username>
      <password>myPasswordOrEncryptedValue</password>
    </server>
  </servers>
</settings>

Tip: you can set the password as a clear text but it is indeed better to use maven encryption.

Once all this configuration done you can upload a directory through FTP with maven using:

mvn wagon:upload@upload-doc

Indeed, a more realistic execution will also generate the documentation (can be an "update the doc" step on your CI). Using JBake it can look like:

mvn jbake:generate wagon:upload@upload-doc

If you need to generate some documentation from the code using exec maven plugin - or groovy one, it can look like:

mvn \
  process-classes \
  exec:java@generate-doc-content \
  jbake:generate \
  wagon:upload@upload-doc

What is really nice with such a solution is that you can upload quite easily the doc per version (just add ${project.version} in target directory). Combined with maven filtering and CLI overrides (-DmyTargetFolder for example) you can fully control what you deploy handling advanced cases quite easily on your CI. You can even regenerate all the version of your website using a new theme...but this is another story ;).