BuildXPages Deployment Automation Tools – v1.0.0
After quite a bit of work I have finally published the first release of BuildXPages!
What is BuildXPages?
BuildXPages is a project which is useful if you are interested in Automating tasks that are involved in building XPages.
For example you may be interested in automating some of these tasks:
- Building NSFs from an On-Disk Project
- Building Plugins and Features
- Refreshing NSF Designs
- Setting Template Inheritance of NSFs
- Start, Stop and Restart Http server
- Uploading Plugins to an NSF Update Site
- Deploy Plugins to Notes/Designer
BuildXPages provides tools which can be used to achieve these tasks. The main artifact of the project is a collection of tasks that can be used in an Ant build script, but the project also includes a Plugin for Domino Designer to facilitate the building of NSFs.
Project Background
Automating the build and deployment of any software application is a great idea to be able achieve the same result every time. Information and tools for doing this in XPages is relatively scarce but you can find blog posts and some tools out there.
I have written a few years ago about the build system for XPages we use at my workplace, and have shared my slides from the talk I gave at AUSLUG 2015 so have a look at those for some background (be aware these posts are old and I may be doing some things differently now), I decided to gather the tools that I have developed to support this and make them available under it’s own Open Source Project.
If you look you will see the project has actually been on Github since 2014! But the project never had any good documentation and some of the parts where not very friendly to use.
Over the last couple of months I have been working away on bringing the project up to a standard where it can be understood and used by others. This includes things like:
- making information and error messages more useful and understandable
- making task names and arguments more user-friendly
- replacing my hard-coded options with configurable options
- most of all .. writing documentation!
Documentation
You can always find the latest Documentation on the Github Project’s Documentation website. The documentation is also contained as PDF and HTML in the release download.
A large part of writing the documentation was trying to figure out how to explain getting your environment setup. Whilst I think I have everything covered there is a every chance I have missed something that may be different for your environment, so if you do try it out and it doesn’t work please don’t hesitate to contact me.
Asciidoctor FTW!
Documentation for the Project is written Asciidoctor using AsciidoctFX and generated using the ant-asciidoctorj plugin. The Asciidoctor ‘toolchain’ is awesome and deserves it’s own blog post / video but that will have to be another day. There is already plenty of information out there about it. If you are going to write any documentation I highly recommend having a look at using it and feel free to ask me about it here or in the XPages Slack chat. You can see the ‘recipe’ I use for generating the documentation by looking at the build.xml file in the root of the project, and you can see all the documentation ‘source’ files in the doc folder.
Demonstration Tutorials
The Project contains some demonstration tutorials which are designed to verify that you have everything set up and to demonstrate the very basic tasks.
Feedback / Problems / Suggestions
I you have any problems with these let me know and I can double check what may be the problem either in your setup, or maybe a bug in the project.
A note about Build Tools
Part of your automation process is deciding what ‘build tool’ you will use, which is usually program that helps coordinate a sequence of tasks that need to be done in order to build / deploy your project. This could be as simple as a batch file, or use a well developed system specifically for this purpose.
I chose Ant because of it’s simplicity and availability of good documentation. It was very easy for me to get up and running and there were many examples out there to follow. I had also tried to give maven a go but found it hard to find good documentation and after a few dead ends just gave up and returned to making progress with ant.
So with Ant as my choice I have written all these custom tasks to work with Ant. Ant is written in Java and so all the tasks are java based, Maven and Gradle are both Java based and I know there are other XPages developers who prefer maven or gradle. If anyone is interested in translating these tasks to be used as a plugin for gradle or maven plugin then I would be happy to help you adapt them and hopefully include them in this project so that others can also use.
Also: if you are using maven be aware there is already the headlessdesigner-maven-plugin which is written about on Christian Guedemann’s blog
I will read it with great interest. thanks!