Multi Environment Maven Plugin

License

Apache License, Version 2.0, January 2004

What's New

###Version 1.1
---------

    - Fixed a bug in Exclude environments. It doesn't strip beginning and end spaces in the comma separated list of environment names.
    - Add feature which adds manifest entries configured on the plugin.
    - Fixed common directory warning message.
    - Changed the command line switch `-Dmem.env` to `-Dem.env`.
    - All environment wars were being built when a single environment is run. This bug is fixed.

Overview

There are several scenarios where you have different configurations for
different environments like dev, test, prod etc. (in real life there are
usually more environments than three.).

Now you need to produce different artifacts for example war files for those
different environments. A combination of maven-assembly-plugin and some
descriptors will solve this. Also this
can be enhanced for other things as well.

The problem becomes worse if you have more than two or three environments than the
configuration with
maven-assembly-plugin etc. became cumbersome.
This plugin will exactly handle such scenarios.

The scenarios are the following. Producing artifacts which include the
configuration for each environment: or artifacts which contain only the
configuration: for the appropriate environment.

Example 1

Let us assume you have several environments like dev-01, dev-02, test-01,
test-02 and finally prod. We will make the situation simpler for this
example and assume having only a single module build which produces a
single war file as a result.

The prerequisite to use the Environments Maven Plugin is to create
a directory structure similar like the following:

 src
  ├── main 
        ├── environments
             ├── dev-01
             │   └── first.properties
             ├── dev-02
             │   └── first.properties
             ├── test-01
             │   └── first.properties
             ├── test-02
             │   └── first.properties
             └── prod
                 └── first.properties

In result the Environments Maven Plugin will automatically create the
appropriate war files containing the configuration file first.properties
(just a single file for brevity in this example) which might contain some information like
the database connections url etc. for the appropriate environment.

You can of course put several different files into the different environment
directories. It is also possible to create a directory structure under the appropriate
environment. This will also be packaged into the resulting artifact.

The environment name (directory name dev-01, dev-02, test-01 etc.) will
automatically being used as classifier for the appropriate artifact. So we
would get the following files after running Environments Maven Plugin via
(assuming you have configured it correctly):

mvn clean package

• artifactId-version-dev-01.war
• artifactId-version-dev-02.war
• artifactId-version-test-01.war
• artifactId-version-test-02.war
• artifactId-version-prod.war

If you need to add a new environment this can simply being achieved by adding a
new directory under environments which might being called qa-01 plus the
information you would like to configure and that's it. Environments Maven
Plugin will automatically identify the new environment by searching in the
environment directory and producing an appropriate artifact out of it.

Those above packages contain the original war file content as well
as the supplemental files/directories which have been given for the
appropriate environments.

Example 2

In this example we would like to create configuration artifacts for
each environment.

The configuration looks exactly the same in Example 1
except for the used goal. So you need to change the
goal from environment to configuration in the plugin configuration.
By using the:

mvn clean package

you will produce the following artifacts:

• artifactId-version-dev-01.jar
• artifactId-version-dev-02.jar
• artifactId-version-test-01.jar
• artifactId-version-test-02.jar
• artifactId-version-prod.jar

As you might already realized that those files are not war files. The
files are jar files which contain the configuration for each environment.

How To Configure

To configure Environments Maven Plugin you simply add the following
to your pom file (we assume here a war file):

  <groupId>groupId</groupId>
  <artifactId>artifactId</artifactId>
  <version>0.1.0-SNAPSHOT</version>
  <packaging>war</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>net.sf.environments-maven-plugin</groupId>
        <artifactId>environments-maven-plugin</artifactId>
        <version>0.3.1</version>
        <executions>
          <execution>
            <goals>
              <goal>environment</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

Filtering

Based on the given directory structure files like first.properties etc. will be
filtered before they are packaged into the resulting artifacts. This means you
can use things like ${project.version} in your files or other self defined
properties.

Environment Specific Filtering

Most of the time resource files for different environments are largely the same. They only have minor differences. In those scenarios it is quite cumborsome to parse through the entire file to find the small changes. It makes sense to put those minor differences in a properties files and move the full files to a common location. For example take logback.xml file. The file is usually only differs in server address, port and a few other things. It makes sense to move those into a properties file in each of the environment directories and move a single logback.xml file into a common location. So the directory structure looks something like this.

• src/
  • main/
    • environments/
      • common/
        • logback.xml
      • dev/
        • envspec.properties
      • ci/
        • envspec.properties
      • qa/
        • envspec.properties

Now all wars will have logback.xml and the logback.xml is filtered using envspec.properties for each environment individually.

With this there will be two steps to filtering:

1. All files in src/main/environments are filtered using the files listed in the filter tags in build section. This includes the common directory.
2. Then environments-maven filters the common files using the key/value pairs from the properties file declared in filters tag inside the configuration segment of environments maven plugin. For this filtering to work user should declare both commonDir and filters attributes.

    <plugin>
        <groupId>net.sf.environments-maven-plugin</groupId>
        <artifactId>environments-maven-plugin</artifactId>
        <version>1.1.0-SNAPSHOT</version>
        <configuration>
            <targetPath>some/where/inside</targetPath>
            <commonDir>common</commonDir>
            <filters>
                <filter>envspec.properties</filter>
            </filters>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>environment</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

NOTE:

- If only commonDir is declared then all the files in commonDir will be included in the archives. 
- If only filters are declared and no commonDir is declared then this will have no impact on the archives.
- If you have no intention of using a common directory you should declare filters in the build section of the pom.

Common Dir

A common dir can be declared using commonDir plugin configuration attribute. Any files inside this
directory will be included in all the wars. This has the same effect as putting the files in src/main/resources.
But this configuration attribute is specifically created to facilitate environment specific filtering. So, to avoid confusion
use commonDir only when you need environment specific filtering.

    <plugin>
        <groupId>net.sf.environments-maven-plugin</groupId>
        <artifactId>environments-maven-plugin</artifactId>
        <version>1.1.0-SNAPSHOT</version>
        <configuration>
            <targetPath>some/where/inside</targetPath>
            <commonDir>common</commonDir>
            <filters>
                <filter>first.properties</filter>
            </filters>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>environment</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Target Path

This will set the path inside the jar to which this resources are copied to.

Ex:

If <targetpath>classes</targetpath> will ensure that resource files from src/main/environments are copied into classes directory in each jar.

    <plugin>
        <groupId>net.sf.environments-maven-plugin</groupId>
        <artifactId>environments-maven-plugin</artifactId>
        <version>1.1.0-SNAPSHOT</version>
        <configuration>
            <targetPath>some/where/inside</targetPath>
            <commonDir>common</commonDir>
            <filters>
                <filter>first.properties</filter>
            </filters>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>environment</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Individual Environment

To copy the files from a particular environment to target/classes pass the em.env user property on the command line.

Ex: mvn clean install -Dem.env=dev

This will copy the filtered contents of src/main/environments/dev into target/classes.

Document:

• Using filename/directory filtering ?
• Different files for different environments

Excluded Environments

There could be scenarios where you may have directories inside src/main/environments for which you don't want to generate archives. For example if you have directories dev-local and qa-local inside src/main/environments
directory and these are useful if a develop wants to run his localhost against dev or qa, then you probably don't want to generate archives for these as that would unncessarily delay your build. Environments-Maven-Plugin provides
excludeEnvironments tag for this purpose.This tag takes comma separted list of directory names. leading and trailing spaces are ignored. So dev,ci,qa,prod is the same as dev, ci, qa, prod.

    <plugin>
        <groupId>net.sf.environments-maven-plugin</groupId>
        <artifactId>environments-maven-plugin</artifactId>
        <version>1.1.0-SNAPSHOT</version>
        <configuration>
            <excludeEnvironments>dev01, qa01 ,qa02,</excludeEnvironments>
            <parallel>true</parallel>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>configuration</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Manifest customization

All jars will have a Environment entry in manifest file as shown below.
Environment: test02

Environment specific maven archive configuration is enabled as shown below. For the environments that don't have an archive configuration specified, default configuration will be used just as it is done for any jar built using maven.

Customization of the Manifest

Environment specific archive configuration can be specified inside <<<environmentarchiveconfiguration>>></environmentarchiveconfiguration> tag.
Multiple <<<environmentarchiveconfiguration>>></environmentarchiveconfiguration> tags can be grouped inside an <<<archives>>></archives> tag.

<<<environmentarchiveconfiguration>>></environmentarchiveconfiguration> tag takes a <<<environment>>></environment> tag and an <<<archive>>></archive> tag.

Environment tag takes a string representing the name of the environment.

The default manifest can be altered with the <<<archive>>></archive> configuration
element. archive is a standard maven tag. Below you will find some of the configuration options that are
available. For more info see the {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver reference}}.

<project>
  ...
  <build>
    <plugins>
      <plugin>
            <groupId>net.sf.environments-maven-plugin</groupId>
            <artifactId>environments-maven-plugin</artifactId>
            <version>1.1.0-SNAPSHOT</version>
            <configuration>
                <excludeEnvironments>dev01, qa01</excludeEnvironments>
                <parallel>true</parallel>
                <archives>
                    <environmentArchiveConfiguration>
                        <environment>dev02</environment>
                        <archive>
                            <manifestEntries>
                                <mode>development</mode>
                                <key>value</key>
                            </manifestEntries>
                        </archive>
                    </environmentArchiveConfiguration>
                    <environmentArchiveConfiguration>
                        <environment>prod01</environment>
                        <archive>
                            <manifestEntries>
                                <mode>development1</mode>
                                <key>value1</key>
                            </manifestEntries>
                        </archive>
                    </environmentArchiveConfiguration>
                </archives>
            </configuration>
            <executions>
              <execution>
                <goals>
                  <goal>configuration</goal>
                </goals>
              </execution>
            </executions>
        </plugin>
    </plugins>
  </build>
  ...
</project>

Advantages

• Much more convenient
• less configuration.
• Dynamically add new environments
• No Profiles needed.

TODO

• Environments Maven Plugin in a different maven project within multi module
  build? How does that work?
• Overwriting of file which exist in the original artifact? How to handle?