<text><lang type="en">Provide Software</lang></text>

<text><lang type="en">Features</lang></text>== Purpose of the Product == To name a standard set of steps, or operations, with which the work of providing software application services can be largely automated. === Desire for Named Operations === Because the work of application service provision responds to new releases of the provided software applications, much of the work is occasional and irregular. Close manual administration is error prone because it's hard manually to keep track of where everything is and what everything has been called. Even worse, because of the extended nature of the activity, when you come back to it you can always think of better ways of doing things, and it can be hard to maintain a standard (and simplifying) scheme for naming things, laying things out, setting things up, and moving things on. Therefore, we wanted to name a standard set of steps, or operations, with which the work of providing application services can be entirely automated. We wanted to be able to direct repeatable sequences with a set of canned scripts, without any loss of underlying control over the deployment, and without any constraints on the variation between applications. The sequences would help the service provider effect state transitions with minimal key strokes. * acquire instructions for new release * take in new release for testing * examine results of functional tests * visit acceptance testing service * put new release into production * reject release == Scope of the Work == The ''Provide'' system supports the user stories below. * Acquire instructions for deployment of provided software application as a service. * Prepare space for deploying a particular software system as an application service. * Establish a purpose designation for a software application service. * Acquire a particular version of a software application. * Deploy software application for functional testing. * Deploy software application for acceptance testing. * Deploy software application for production usage. * Initialize deployed software application with default domain data. * Initialize deployed software application with dumped domain data. * Designate software application service with a purpose. * Show which application service is designated for a particular purpose. * Dump domain data from an application service. * Acquire instructions for migrating domain data from one version to another. * Migrate domain data dump between two different software service versions. * Designate application service as down for maintenance. * List application service provision entities. * Remove domain data dump from a service. * Remove software application service. * Remove distribution of software application release. * Remove application service provision system. The tutorial on the Documentation page describes how to use the ''Provide'' system. == Scope of the System == There is, pretty much, one ''Provide'' command for each user story listed above. Refer to the ''Provide'' user tutorial on the Documentation page for detailed information.

<text><lang type="en">Documentation</lang></text><br /> 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 ''<nowiki>ScanBooker</nowiki>'' 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.