There are three pieces of documentation for Provide users.
A tutorial introduces new users to the Provide system. A few examples of real world deployments of the Provide system are provided. We are also beginning to describe the Provide plugin API, used to insert adapters for provided applications.
You can download and install Provide from the Download page.
Tutorial
The Provide system is currently a command line tool for application service provision. Commands have been developed to support stepping through the work described on the Features page.
Acquire Instructions For New Release
Before any application service can be provided, instructions for downloading and deploying the application must be acquired.
The following command makes available within your Provide user environment a set of scripts tailored for the new release.
provide scripts <app> <version>
A set of standard sequences of Provide commands configured for a particular software application release will be downloaded and installed locally.
You can tab-complete (from "provide-") in your terminal to see which scripts are installed.
These scripts contain standard patterns of Provide commands, configured with all the right versions, download locations, and data migration plans for a particular release.
There are only a small number of patterns, and it's much simpler to invoke the sequences by name (as a script) than it is to figure out and type correctly all the steps and the parameters that are involved in a sequence for a given release.
Let's look at how the scripts fit into the work. Then, we can look at the commands involved in each script.
Acquire New Release
The work of acquiring a new release involves deciding to download and install a released version of a software application.
If the application has not been provided before, the application provision will need to be initialised:
provide-<app>-init
Storage-space for the application is established, along with a set of "purposes" with which deployed services will be aliased into URL-space.
Once the application provision has been initialised, the new release can be acquired:
provide-<app>-<ver>-init
The released files are downloaded, and stored locally on disk.
Evaluate Results of Functional Tests
This work involves checking whether the release passes automated functional testing.
If the application is being deployed for the first time, deploy with default domain data:
provide-<app>-<ver>-accept
Otherwise, deploy with migrated domain data:
provide-<app>-<ver>-accept-from-<prev>
The release will be deployed for functional testing, and the tests will be run automatically. If the functional tests fail, the script will terminate. At this point, a decision is normally made to remove the release (see below) and feedback to the developers.
Otherwise, the release will be immediately deployed for acceptance testing.
If all goes well, the acceptance testing purpose will be switched to alias the new acceptance testing service.
Remove Release
This work involves removing everything to do with the release.
Remove release:
provide-<app>-<ver>-remove
Removing the release in this way will remove all the services, downloaded code, everything to do with the release. All changed service purposes will be switched back to alias the old version services.
The release can now be fixed and updated, and the previous steps repeated as if for the first time.
Evaluate Acceptance Testing Service
This work involves actually using the software application as a production service, but in a different location from the actual production service location.
Just visit the acceptance testing location for this application, and check everything is okay.
If the acceptance testing service is unacceptable, a decision is made to remove the release (see above). So far, nothing has have happened to disturb any current production service, and the whole routine can be repeated many times without any production downtime.
If the acceptance testing service is acceptable, a decision can be made to put the release into production. It is advisable to schedule a maintenance window for production cut-over, just in case anything bad happens (which is very unlikely because all the steps have by now been rehearsed).
Cutover Production Service
This work involves repeating the deployment of the acceptance testing service, but this time in the name of "production" rather than "acceptance testing".
If the application is being deployed for the first time, deploy the release with default domain data:
provide-<app>-<ver>-production
Otherwise, deploy the release with migrated domain data:
provide-<app>-<ver>-production-from-<prev>
If all goes well, the production service purpose will be switched to alias the new production service.
It's always worth verifying that the upgraded production service appears to be working. Just visit the production service location for this application, and check everything is okay.
If the new version production service is unacceptable, a decision is made to remove the release (see above). Both the production and acceptance testing purposes will be switched back to alias old version services. Again, it is always worth checking the old services are being served again.
Commands Involved in the Sequences
Of course, the commands can all be run individually to generate exactly the same results. The scripts merely provide a highly repeatable cycle.
Initialise Provision
Firstly, the application provision is established. Secondly, the purpose designations are established.
Establish Application Provision
The application provision is named after the software application that is provided.
provide provision <app> <url>
The named application will be distributed at the given resource location.
Establish Purpose Designation
It is common to establish 'production', 'accept', and 'test' purposes. The same command is used once for each purpose.
provide purpose <app> test provide purpose <app> accept provide purpose <app> production
Purpose designations provide an invariant point of reference and access for users across successive releases of the application.
Acquire Release
This sequence involves acquiring the release, any explicit dependencies, and the prepared migration plans.
Acquire System
provide release <app> <ver>
Downloads and saves in a standard place a release of the application.
Acquire Dependency
provide depends <app> <ver> <dependency>
Downloads and saves in a standard place a release of a dependency of the release.
Acquire Migration Plan
provide plan <app> <ver> <path>
Downloads and saves in a standard place the released migration plan, used for moving domain data between different model versions.
Deploy Release for Acceptance Testing and Production Usage
These sequences involve deploying the downloaded software in various ways.
After creating a new service, either run the tests ('test' service), or commission the service with default or migrated domain data ('accept' and 'production' services).
Finish up by designating the new services for the applicable purpose.
Create New Service
Deploy the software to create a service.
provide deploy <app> <ver> <service>
Unpacks, installs, configures, and tweaks files from both downloaded distribution and explicit dependencies to a standard location named after the given service name.
Run Tests
Instead of commissioning a deployment with default or migrated data, you can run the application's automated test suite and see if this version of the application system functions on the host platform.
provide test <app> <ver> <service>
It is usual not to use a service for acceptance testing or production usage after the automatic tests have been run against it.
Commission with Default Domain Data
The first time the application is deployed it will need to be initialized in the default 'out-of-the-box' state.
provide commission <app> <ver> <service>
Setting up with default domain data is the way to start using the application. Once the application has been in production, to maintain continuity of service to users, it will be necessary for subsequent releases to be loaded with migrated data (see below).
Commission with Migrated Domain Data
To migrate domain data between services, simply dump, then move and load the domain data into new service. The operation uses one of the acquired migration plans (see above) according to the releases involved.
provide datadump <app> <ver1> <service1> <dump1>
Exports the domain data as a JSON string, and writes it to a text file.
provide datamove <app> <ver1> <service1> <dump1> <ver2> <service2> <dump2>
Reads the dump file, loads and transforms the domain data, and writes the result to a second text file.
provide dataload <app> <app> <service2> <dump2>
Reads the dump file, and imports the domain data from the JSON string.
Designate Deployed Application For Purpose
When it's time to cut-over a purpose to a new version of the provided application, the thing is to designate the new service for that purpose. In the standard sequences, this is done firstly for the acceptance service, so the version can be used by acceptance testers without any change to the production service. Later, when acceptance testing is complete, the new production service is designated as the production purpose and users seamlessly continue to use the service.
provide designate <app> <ver> <service> <purpose>
Switches the purpose to use a particular deployment.
Link Release to a Service
Some times one provided application will depend on another. For example, KForge expects Trac to be installed. Provide can deploy Trac and KForge, and link Trac to KForge so KForge has its Trac.
provide link <depapp> <depver> <depservice> <app> <ver>
Clean Up
Remove Dump, Service, Release
There is a sequence for removing things. This is particularly useful when acceptance testing has failed. The software system can be adjusted, the release updated, and the application service provision process restarted from the 'initialize version' sequence many times without distracting from the software development work.
provide rmdump <app> <ver> <service> <dump>
Deletes domain data dump.
provide rmservice <app> <ver> <service>
Deletes application service (and all its data dumps).
provide rmrelease <app> <ver>
Deletes application version (and all its deployed services).
Remove Provision
provide rmprovision <app>
Deletes application provision (and all its established versions).
Other Useful Commands
Help
The Provide system can print brief help messages.
provide help [command]
Prints a usage message about the named command.
What's Been Installed?
The provisions that have been declared can be listed. Also, their releases and the services which have been deployed from these releases can also be listed.
provide provisionlist
Lists application service provisions.
provide releaselist <app>
Lists the installed releases of named application service provision.
provide servicelist <app> <ver>
Lists services that have been deployed using a given release.
Which Service Is Used By This Purpose?
Sometimes you forget, of all the different deployed services, which is actually in production.
provide which <app> <purpose>
Prints the version and service name designated for that purpose.
Where are the Application Files?
It's important to be able to get directly to the installed application files.
provide path <app> <ver> <service>
Prints the file system path to the root of the application installation. What's here depends on the application system, and the corresponding Provide plugin.
Examples
UK's Medical Research Council
The Cognition and Brain Sciences unit of the Medical Research Council use Provide to maintain their ScanBooker deployment.
Appropriate Software Services
Many application services of appropriatesoftware.net are maintained using Provide.
API Documentation
Plugin API
Each provided application must have a corresponding Provide plugin, which acts as an adapter between Provide and the provided application. The software for the Provide plugin must be installed into the Provide installation before the application provision is declared.
When loaded, an application plugin will listen to Provide domain model events, and selectively take application-specific actions in response to relevant Provide domain model state transitions.
There is a Provide plugin base class, from which all the application plugins derive. There is also a domainmodel base class, from which all domainmodel applications derive. In future, other base classes may exist for other shapes of software application.
The Provide plugin base class declares empty methods that are called by its event handlers. Plugin developers are responsible for making sure their plugin has implementations of these methods that are suitable for the plugged in application.
- Todo: More about plugin methods.
Please refer to the source code (which is very readable) for full details.