This repository has been archived by the owner on Apr 16, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #93 from niels-nijens/documentation
Added documentation
- Loading branch information
Showing
14 changed files
with
368 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| # Getting started | ||
|
|
||
| Accompli is a tool to automate deployment of (PHP) projects. It allows you to easily configure (and create) a set of tasks | ||
| and run the task when deploying a release of your project. | ||
|
|
||
| We aim provide support for [Testing-Acceptance-Production][link-wikipedia-dtap], [Continuous Delivery][link-wikipedia-continuous-delivery] and [Continuous Deployment][link-wikipedia-continuous-delivery] concepts. | ||
|
|
||
| ## Why the name 'Accompli'? | ||
|
|
||
| Accompli is the French word for 'accomplished' or 'finished'. | ||
| This fits well with deploying your project, as it most likely to be done. | ||
| The French originates back to when Accompli was mainly meant to be a deployment tool for | ||
| Symfony Framework projects. Which is created by SensioLabs, a French company. | ||
|
|
||
| ## System Requirements | ||
|
|
||
| Accompli requires PHP 5.4.0+ to run. | ||
|
|
||
| The following extensions are suggested to speed up SSH related tasks: | ||
| * mcrypt | ||
| * openssl | ||
|
|
||
| In order to install releases from version control, you will need to have git or subversion | ||
| installed depending on how your project is version-controlled. | ||
|
|
||
| Accompli is multi-platform and we strive to make it run equally well on Windows, Linux and OSX. | ||
|
|
||
| ## Installation using Composer | ||
|
|
||
| Run the following command to add the package to the composer.json of your project: | ||
|
|
||
| ``` bash | ||
| $ composer require accompli/accompli:dev-master --dev | ||
| ``` | ||
|
|
||
| ## Using Accompli | ||
|
|
||
| In order for Accompli to run you require a accompli.json file in the root of your project. | ||
| This will contain the configured hosts to deploy to and the tasks to run during deployment of a release. | ||
|
|
||
| An example accompli.json: | ||
| ``` json | ||
| { | ||
| "$extend": "vendor/accompli/accompli/src/Resources/accompli-defaults.json", | ||
| "hosts": [ | ||
| { | ||
| "stage": "test", | ||
| "connectionType": "ssh", | ||
| "hostname": "example.com", | ||
| "path": "/var/www/example.com" | ||
| } | ||
| ], | ||
| "events": { | ||
| "subscribers": [ | ||
| { | ||
| "class": "Accompli\\Task\\CreateWorkspaceTask" | ||
| }, | ||
| { | ||
| "class": "Accompli\\Task\\RepositoryCheckoutTask", | ||
| "repositoryUrl": "https://github.com/example.com/example.com.git" | ||
| }, | ||
| { | ||
| "class": "Accompli\\Task\\DeployReleaseTask" | ||
| }, | ||
| { | ||
| "class": "Accompli\\Task\\MaintenanceModeTask" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For more detailed information on how to configure your accompli.json, please see the [configuration](Configuration.md) documentation. | ||
|
|
||
| See the [tasks](Tasks.md) documentation to learn what tasks are provided by Accompli and how to create your own tasks. | ||
|
|
||
| ### Install a release for deployment | ||
| To install a release for deployment you need to run the following command from your project root: | ||
|
|
||
| ``` bash | ||
| $ vendor/bin/accompli install-release <version> | ||
| ``` | ||
|
|
||
| Accompli will then run the configured installation tasks for all configured hosts. | ||
|
|
||
| Optionally, you can install a release on hosts with a specific stage configured: | ||
|
|
||
| ``` bash | ||
| $ vendor/bin/accompli install-release <version> <stage> | ||
| ``` | ||
|
|
||
| ### Deploy a release | ||
|
|
||
| To deploy a previously install release you need to run the following command from your project root: | ||
|
|
||
| ``` bash | ||
| $ vendor/bin/accompli deploy-release <version> <stage> | ||
| ``` | ||
|
|
||
| During a deployment Accompli is able to determine wether the deployment is a rollback to a previous version or an increment to a new version. | ||
|
|
||
| *C'est fini! Accompli!* | ||
|
|
||
|
|
||
| [link-wikipedia-dtap]: https://en.wikipedia.org/wiki/Development,_testing,_acceptance_and_production | ||
| [link-wikipedia-continuous-delivery]: https://en.wikipedia.org/wiki/Continuous_delivery | ||
| [link-wikipedia-continuous-deployment]: https://en.wikipedia.org/wiki/Continuous_deployment |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| # Configuration | ||
| This chapter will explain all the available sections of the accompli.json configuration. | ||
|
|
||
| ## Using a recipe | ||
| A recipe is a set of pre-configured tasks defined in a separate accompli.json file. | ||
|
|
||
| You can include a recipe by referencing it in the '$extend' key: | ||
| ``` json | ||
| { | ||
| "$extend": "vendor/accompli/accompli/src/Resources/accompli-defaults.json" | ||
| } | ||
| ``` | ||
|
|
||
| The path to the recipe can be relative to the location of the accompli.json in your project. | ||
|
|
||
| ## Configuring a host | ||
|
|
||
| Hosts are configured in an array within the 'hosts' key. | ||
|
|
||
| A host object requires the following keys: | ||
| * stage - The deployment stage a host is part of (test, acceptance, production). | ||
| * connectionType - The identifier of a connection adapter to communicate with the host. | ||
| * hostname - The IP address or DNS hostname of the host. | ||
| * path - The absolute path to the workspace on the host. | ||
|
|
||
| ``` json | ||
| { | ||
| "hosts": [ | ||
| { | ||
| "stage": "test", | ||
| "connectionType": "ssh", | ||
| "hostname": "example.com", | ||
| "path": "/var/www/example.com" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Optionally, a 'connectionOptions' key can be configured within a host object with an array of connection adapter specific configuration parameters. | ||
|
|
||
| For more information on the specific connection options, please see the [connection adapter](Connection-adapters.md) documentation. | ||
|
|
||
| ## Configuring a task | ||
|
|
||
| Tasks are mostly configured as an event subscriber, but can also be configured as event listener for a specific event. | ||
|
|
||
| To configure a task as an event subscriber add your class to the 'events.subscribers' keys: | ||
|
|
||
| ``` json | ||
| { | ||
| "events": { | ||
| "subscribers": [ | ||
| { | ||
| "class": "My\\Namespaced\\Task" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| If your task has constructor arguments to configure it's behavior, you're able to configure them next to the class name of the task: | ||
|
|
||
| ``` json | ||
| { | ||
| "events": { | ||
| "subscribers": [ | ||
| { | ||
| "class": "My\\Namespaced\\Task", | ||
| "argument1": "value", | ||
| "argument2": 2 | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For more information about tasks and a list of available Accompli tasks, see the [tasks](Tasks.md) documentation. | ||
|
|
||
| ## Configuring the deployment strategy | ||
|
|
||
| A deployment strategy is configured in the 'deployment.strategy' keys by setting the class name: | ||
|
|
||
| ``` json | ||
| { | ||
| "deployment": { | ||
| "strategy": "Accompli\\Deployment\\Strategy\\RemoteInstallStrategy" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Configuring connection adapters | ||
|
|
||
| Connection adapters are configured in the 'deployment.connection' keys with a unique identifier and the class name of the connection adapter: | ||
|
|
||
| ``` json | ||
| { | ||
| "deployment": { | ||
| "connection": { | ||
| "uniqueIdentifier": "My\\Namespaced\\ConnectionAdapter" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The identifier can then be used to configure the 'connectionType' key of a host. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.