Recommended Development and Build/Deployment Process ==================================================== DPBuddy can support any build/deployment/release process; however, you will get the most value out of DPBuddy if you follow a structured release process with strict separation of environments and reliance on version control. In short, the build/deployment process of your DataPower artifacts should be similar to the process used for any "regular" Java EE or Java application. The process should include the steps for creating the build, deploying it to a test environment, performing testing, promoting the build to a "higher" environment and so on. A suggested process is described below. Your DPBuddy distribution includes sample files implementing this process. You can find these files under ``samples/ant-end-to-end``, where ``dp-build-deploy.xml`` is the name of the Ant file; the same file is also available `online `. The text below references the relevant target names in this file. DPBuddy provides tasks/commands to fully automate all the steps described below. .. _developing_dp: Developing DataPower Artifacts ------------------------------ You can have many domains used for development, e.g., you could set up different domains for testing different services. Developers can modify configuration/artifacts in their domains as needed by following these general steps: * Create/update DataPower services and objects using WebGUI. * Upload various files used by DataPower services using the :ref:`copy` task. Target: ``upload.files``. * Conduct testing using JUnit, `SoapUI `_ or other tools. * Export DataPower configuration using the :ref:`export` task and `check in the configuration file under version control `_ . We recommend checking in XML configuration files (as opposed to exported .zip files) so that version control can be used to track changes and diff the files. Note that DPBuddy will automatically clean and format the exported XML configuration so that it can be checked in right away. Target: ``export.services``. We recommend replacing environment-dependent values with variables during export. This can be done using the ``transform`` element of the :ref:`export` task. As a result, you will create a "canonical" environment-independent configuration. Changes to this configuration can be easily tracked using a version control system. .. _test_env: Creating a Build in a Test Environment -------------------------------------- Test environment or a test domain can be used for assembling all services, objects and files required for the release. After this is done, the entire domain (which could include multiple domains in a complex system) should be treated as a releasable artifact. The export of the test domain is analogous to a deployable Java EE application file, such as a WAR or an EAR archive. * Delete and create the test domain. You should always start from a "clean slate" to avoid issues that might be caused by objects created during an earlier test cycle. To create an empty domain simply export a domain definition from the "default" domain (by navigating to "Application Domains" in WebGUI or by running DPBuddy's :ref:`export` task) and import the definition with the new name. Targets: ``export.domain.definition``, ``create.clean.domain``. * Upload certificates/keys required for crypto objects. Keys should be stored in a separate protected area, so they have to be uploaded as a separate step. Target: ``upload.certs``. * Check out a release tag/label from version control. The baseline must include all files and configuration artifacts required to build a fully functioning domain. You can utilize a CI/Build server such as Jenkins/Hudson to perform this task. * Import configuration of the crypto objects. Crypto configuration (but not the keys themselves) could be stored under version control, and can be imported using the :ref:`import` task similar to any other DataPower service or object. Target: ``import.crypto.config``. * Upload files used by DataPower services and objects. This should cover all XSLT, WSDL, XSD and all the other files that have to reside on the DataPower filesystem (usually, under ``local:/``). Target: ``upload.files``. * Import DataPower configuration, including all objects and services. You may need to update your configuration to adapt it to the target environment using :ref:`DPBuddy's configuration transformation capabilities `. Target: ``import.services.config``. * Verify the import and save the domain's configuration. You can use various DPBuddy assertion tasks, such as :ref:`assertState` for this purpose. Target: ``verify.import``. * Export the entire domain. This export constitutes the "build" of DataPower artifacts that could be promoted to other environments after testing is done. You can use a Maven repo or version control to store the domain export. You should handle it same way you deal with binary build artifacts produced by application builds, such as WAR and EAR files. Target: ``export.domain``. * Conduct automated or manual testing of deployed services. You can incorporate SoapUI test targets into your Ant file as described `here `_. .. _higher_env: Promoting the Build to a "Higher" Environment --------------------------------------------- The domain export created during the "build" step should be deployed (promoted) to other environments as a whole; ideally there should be a single "import" target to perform the entire deployment. * :ref:`Quiesce the target domain `. You can quiesce the entire domain or specific services running in the domain. Target: ``quiesce.domain``. * Clean the domain. You could either delete and create the domain or clean it. If you don't want to re-upload keys every time you deploy, it might be enough to simply reset the domain (using the :ref:`resetDomain` task) and delete the content of the ``local:/`` filesystem (using the :ref:`delete` task). Target: ``clean.domain``. * Import the "build" (the export of the test domain). Depending on your process, you may need to first retrieve the file from version control or from a Maven repo. Alternatively, you could promote the build using your build/CI server. Target: ``import.domain``. * Similar to deploying to a test environment, you should verify that all newly imported objects and services are up and running. Target: ``verify.import``. * Create the checkpoint and export the domain's configuration in XML format (without files). This configuration could be put under version control to create a complete history of all changes in a specific domain. Target: ``checkpoint``. * Conduct smoke testing. .. _prod_env: Deploying to a Production Environment ------------------------------------- Deploying to a production environment should generally follow the steps outlined in the previous section. There are normally multiple devices employed in production so you will need to repeat these steps multiple times. This may be scripted in Ant/Gradle (see ``deploy.2devices`` target) or, if a manual smoke testing/verification is involved, the same target could be executed multiple times with different environment prefixes.