Providing a custom Plugin for a cloud-hosted UM

The following article describes how you can create and publish a custom UM plugin that is to be integrated into a cloud-hosted UM at AWS.

1. Create plugin using Kickstarter

Follow Install Kickstarter to prepare your local machine to create and develop Kickstarter-based UM projects.

Then, choose a Java-style package name for your new plugin – e.g. acme.projectx. (See also ACME Corporation)

Please note that com..., net... and org... denote reserved namespaces and can not be used as top-level package names.

Create a fresh plugin like this:

umkickstarter MY-PLUGIN-DIR -n acme.projectx

Follow Kickstarter.md to develop your new plugin locally.

2. Provide meaningful artifact names

Edit build.gradle and change the default project name and group id to something meaningful. These settings will make up the name of the artifact that you will publish later on.

pinuts.projectName = 'RestServices'
pinuts.groupId = 'acme.projectx'

3. Prepare publishing the plugin

If Pinuts is hosting your UM installation at AWS, there already is an S3 bucket ready to be used as a maven repository. Ask us for the respective credentials: support@pinuts.de

You will receive an S3 bucket name and AWS access key.

Insert the following into your build.gradle file right after pinuts.version = ... and fill-in BUCKET_NAME with the name you just received:

...
// pinuts.projectName = 'RestServices'
// pinuts.groupId = 'acme.projectx'
// pinuts.version = getVersionFromPluginDescriptor('the_plugin/plugin.desc.json')

publishing {
    publications {
        cmsbsPlugin(MavenPublication) {
            groupId = pinuts.groupId
            artifactId = pinuts.projectName
            version = "${pinuts.env}-SNAPSHOT"
            artifact getCmsbsPluginDistFile()
        }
    }
    repositories {
        maven {
            name "s3bucket"
            url "s3://BUCKET_NAME/snapshots"
            credentials(AwsCredentials) {
                accessKey awsCredentials.AWSAccessKeyId
                secretKey awsCredentials.AWSSecretKey
            }
        }
    }
}

Put the AWS credentials you received into the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY respectively.

After that you can build and publish your plugin like this:

gradle publish                   # -> acme.projectx:RestServices:devel-SNAPSHOT
gradle publish -Penv=staging     # -> acme.projectx:RestServices:staging-SNAPSHOT
gradle publish -Penv=prod        # -> acme.projectx:RestServices:prod-SNAPSHOT

4. Have Pinuts integrate your plugin

After your new plugin has been published to the respective S3 bucket, contact support@pinuts.de to have us integrate the new plugin into your UM cloud deployment.

Tell us the full maven artifact name of the plugin and which SNAPSHOT or VERSION should go on which environment.

We will also give you an HTTP endpoint to trigger a deployment to devel, staging or prod.

5. Trigger deployment

You will be able to trigger a deployment of your published plugin into the cloud-hosted UM by sending an HTTP request to our GitLab like this:

curl -X POST -F token=$TOKEN -F ref=$REF_NAME https://gitext.pinuts.de/api/v4/projects/$PROJECT_ID/trigger/pipeline

We will provide you with the appropriate values for TOKEN and PROJECT_ID. REF_NAME is the name of the destination environment and should always be devel, staging or prod.