modules/autopilot/README.txt

AutoPilot 2.0
=============

AutoPilot is a build and deployment management system for Drupal. Using AutoPilot, you can easily migrate code and configuration changes from development environments to QA and production environments. This document will help you get started with AutoPilot.

CONTENTS OF THIS FILE
---------------------

 * Requirements
 * Optional Tasks
 * Pear Version Control Installation
 * Installation
 * Basic Setup

REQUIREMENTS
------------

AutoPilot requires Drupal 5.x and PHP 5 (5.2.0 or greater) (http://www.php.net/).

The Pear VersionControl_SVN is also required to use the SVN repository.

It also requires the PHP SSH2 library (http://pecl.php.net/package/ssh2). This 
will probably have to be compiled from source as it is not a standard library.

The PHP mcrypt library is also required (http://php.net/mcrypt).

For more detailed information on the php ssh2 library, see the Workhabit Blog post (TBD) 
on the Workhabit site.

PEAR VERSIONCONTROL INSTALLATION
--------------------------------

1. INSTALL PEAR

	Make sure that PEAR is installed on your system (http://pear.net).

2. INSTALL VERSIONCONTROL

	Install the VersionControl_SVN pear module. You may have to use the "-alpha" mod.
	
	pear install VersionControl_SVN-alpha


INSTALLATION
------------

1. DOWNLOAD DRUPAL

	Download Drupal (http://www.drupal.org) and install Drupal as you normally would.

2. DOWNLOAD AutoPilot AND DEPENDENCIES
	
	You will need to download AutoPilot from the Workhabit repositories.
	
	You will also need to download the following dependent modules from the Workhabit
	repository:
		- Ponto Version Control (ponto_vc)
		- Ponto KeyChains (ponto_keychains)
		- Subversion implementation for Ponto Version Control (svn)

3. ENABLE THE MODULES
	Enable the following modules:
		- AutoPilot
		- AutoPilot Feature Sets
		- Ponto Keychains
		- Ponto VC
		- SVN for Ponto VC

BASIC SETUP
-----------

After AutoPilot and it's modules are installed, there are some basic setup procedures that one should implement.

1. INITIALIZE THE KEYCHAIN KEY

	Navigate to the settings page for the Ponto Keychain (admin/settings/keychains).
	Click "save" to set that as the crypt key to use. 

2. CREATE A KEYCHAIN(S)

	A Keychain is the way one authenticates to various resources. With that said, it 
	follows that it is a very important building block of the system. To start off 
	it is recommended that one creates keychains to authenticate to the code repository 
	and to the environment boxes where one will be building their sites to, as you will 
	need these later.
	
	When you create them be SURE to create SYSTEM keychain types.

3. SETUP A BASIC REPOSITORY

	Navigate to the ponto_vc settings to setup a code repository to use (admin/ponto_vc).
	Use the "Add Repository" section to setup a repository. 
	
	You may want to click "update logs" a few times to go ahead and get the logs read in 
	if your cron has not run yet. It should be noted that the logs are refreshed only on
	cron runs unless they are manually triggered using this page.
	
4. CREATE AN AUTOPILOT

	Now we can create an AutoPilot (node/add/autopilot). Just give it a name and description.
	Something like:
	
		Title: My Quotes Project
		Description: This is my personal project. This AutoPilot houses all the 
		buildplans and information for my "Quotes" project.

5. CREATE A WEB TARGET

	One we have our AutoPilot, we can start to create some items that the AutoPilot (AP) 
	will need to do its job. One of these is a Web Target. This is basically the place 
	that your web pages are served from and/or your web server (most likely just a linux box).
	
		- Click the "Setup" tab while inside your AutoPilot.
		- Click "Targets"
		- Click "Add target"
		- Select "Web/HTTP Target Server" from the drop down
		- Enter in the necessary information.

6. CREATE A MYSQL TARGET

	Now we need to create a MySQL target. This is where the database resides.
		- Click the "Setup" tab while inside your AutoPilot.
		- Click "Targets"
		- Click "Add target"
		- Select "MySQL Target Server" from the drop down (Postgres coming soon)
		- Enter in the necessary information.

7. CREATE A BUILD

	A "build" is basically our code bundle. A build is composed of:
		1) Repository root path
		2) Path in the repository to the code.
		
	So if your repository is: 
		http://svn.example.com/myproject
		
	Then your "build" for your code maybe:
		/html ==> (which is: http://svn.example.com/myproject/html)
		
	And your SQL "build" maybe:
		/sql ==> (which is: http://svn.example.com/myproject/sql)
	
		1) Click "Setup"
		2) Click "Builds"
		3) Example the "Add New Build"
		4) Select your repository from the drop down
		5) Select the path to your code in the "Path" section
		6) Give it a title
		7) Select the type of build (code or SQL)
		8) Click "Add Build" ( This adds it as a general "build" you can select and add 
		    to different project/AP's.)
		9) Expand the "Add Existing Build" section
		10) Select the build your just created.
		11) Click "Add Build to AutoPilot"
		
8. CREATE A BUILDPLAN

	Now we can create a Build Plan. This is what actually creates our site. It is the 
	collection of targets and builds that makes our build plan.
	
	1) Click "Create new Buildplan" while inside your AP
	2) Give the Buildplan a title (HEAD - Quotes Project)
	3) Give a description.
	4) Select a "Label"
	
	Build Matrix
	
		You will be presented with a "Build Matrix". 
		The rows on the table represent an "Endpoint", like a webserver 
		or database server.
		
		The columns of the table represent the "builds" or "codes" and where that 
		should go.
		So if you are reading the table from left to right, the first row would 
		read something like:
		
		"For my webserver (col. 1), I want my trunk code (col 2) to go to my 
		development server (col 3).".
		
		You will notice in the drop downs that you can select any of the targets 
		and/or builds that you have created.
		
	5) Click "Create Build Plan"

9. RUN A BUILDPLAN

	Select the build plan you have just created by clicking "view" on the "Buildplan" 
	section of your AP.
	
	From there, select what repository version you wish to use, and just click 
	"Run Build".
1	AutoPilot 2.0
2	=============
3
4	AutoPilot is a build and deployment management system for Drupal. Using AutoPilot, you can easily migrate code and configuration changes from development environments to QA and production environments. This document will help you get started with AutoPilot.
5
6	CONTENTS OF THIS FILE
7	---------------------
8
9	* Requirements
10	* Optional Tasks
11	* Pear Version Control Installation
12	* Installation
13	* Basic Setup
14
15	REQUIREMENTS
16	------------
17
18	AutoPilot requires Drupal 5.x and PHP 5 (5.2.0 or greater) (http://www.php.net/).
19
20	The Pear VersionControl_SVN is also required to use the SVN repository.
21
22	It also requires the PHP SSH2 library (http://pecl.php.net/package/ssh2). This
23	will probably have to be compiled from source as it is not a standard library.
24
25	The PHP mcrypt library is also required (http://php.net/mcrypt).
26
27	For more detailed information on the php ssh2 library, see the Workhabit Blog post (TBD)
28	on the Workhabit site.
29
30	PEAR VERSIONCONTROL INSTALLATION
31	--------------------------------
32
33	1. INSTALL PEAR
34
35	Make sure that PEAR is installed on your system (http://pear.net).
36
37	2. INSTALL VERSIONCONTROL
38
39	Install the VersionControl_SVN pear module. You may have to use the "-alpha" mod.
40
41	pear install VersionControl_SVN-alpha
42
43
44	INSTALLATION
45	------------
46
47	1. DOWNLOAD DRUPAL
48
49	Download Drupal (http://www.drupal.org) and install Drupal as you normally would.
50
51	2. DOWNLOAD AutoPilot AND DEPENDENCIES
52
53	You will need to download AutoPilot from the Workhabit repositories.
54
55	You will also need to download the following dependent modules from the Workhabit
56	repository:
57	- Ponto Version Control (ponto_vc)
58	- Ponto KeyChains (ponto_keychains)
59	- Subversion implementation for Ponto Version Control (svn)
60
61	3. ENABLE THE MODULES
62	Enable the following modules:
63	- AutoPilot
64	- AutoPilot Feature Sets
65	- Ponto Keychains
66	- Ponto VC
67	- SVN for Ponto VC
68
69	BASIC SETUP
70	-----------
71
72	After AutoPilot and it's modules are installed, there are some basic setup procedures that one should implement.
73
74	1. INITIALIZE THE KEYCHAIN KEY
75
76	Navigate to the settings page for the Ponto Keychain (admin/settings/keychains).
77	Click "save" to set that as the crypt key to use.
78
79	2. CREATE A KEYCHAIN(S)
80
81	A Keychain is the way one authenticates to various resources. With that said, it
82	follows that it is a very important building block of the system. To start off
83	it is recommended that one creates keychains to authenticate to the code repository
84	and to the environment boxes where one will be building their sites to, as you will
85	need these later.
86
87	When you create them be SURE to create SYSTEM keychain types.
88
89	3. SETUP A BASIC REPOSITORY
90
91	Navigate to the ponto_vc settings to setup a code repository to use (admin/ponto_vc).
92	Use the "Add Repository" section to setup a repository.
93
94	You may want to click "update logs" a few times to go ahead and get the logs read in
95	if your cron has not run yet. It should be noted that the logs are refreshed only on
96	cron runs unless they are manually triggered using this page.
97
98	4. CREATE AN AUTOPILOT
99
100	Now we can create an AutoPilot (node/add/autopilot). Just give it a name and description.
101	Something like:
102
103	Title: My Quotes Project
104	Description: This is my personal project. This AutoPilot houses all the
105	buildplans and information for my "Quotes" project.
106
107	5. CREATE A WEB TARGET
108
109	One we have our AutoPilot, we can start to create some items that the AutoPilot (AP)
110	will need to do its job. One of these is a Web Target. This is basically the place
111	that your web pages are served from and/or your web server (most likely just a linux box).
112
113	- Click the "Setup" tab while inside your AutoPilot.
114	- Click "Targets"
115	- Click "Add target"
116	- Select "Web/HTTP Target Server" from the drop down
117	- Enter in the necessary information.
118
119	6. CREATE A MYSQL TARGET
120
121	Now we need to create a MySQL target. This is where the database resides.
122	- Click the "Setup" tab while inside your AutoPilot.
123	- Click "Targets"
124	- Click "Add target"
125	- Select "MySQL Target Server" from the drop down (Postgres coming soon)
126	- Enter in the necessary information.
127
128	7. CREATE A BUILD
129
130	A "build" is basically our code bundle. A build is composed of:
131	1) Repository root path
132	2) Path in the repository to the code.
133
134	So if your repository is:
135	http://svn.example.com/myproject
136
137	Then your "build" for your code maybe:
138	/html ==> (which is: http://svn.example.com/myproject/html)
139
140	And your SQL "build" maybe:
141	/sql ==> (which is: http://svn.example.com/myproject/sql)
142
143	1) Click "Setup"
144	2) Click "Builds"
145	3) Example the "Add New Build"
146	4) Select your repository from the drop down
147	5) Select the path to your code in the "Path" section
148	6) Give it a title
149	7) Select the type of build (code or SQL)
150	8) Click "Add Build" ( This adds it as a general "build" you can select and add
151	to different project/AP's.)
152	9) Expand the "Add Existing Build" section
153	10) Select the build your just created.
154	11) Click "Add Build to AutoPilot"
155
156	8. CREATE A BUILDPLAN
157
158	Now we can create a Build Plan. This is what actually creates our site. It is the
159	collection of targets and builds that makes our build plan.
160
161	1) Click "Create new Buildplan" while inside your AP
162	2) Give the Buildplan a title (HEAD - Quotes Project)
163	3) Give a description.
164	4) Select a "Label"
165
166	Build Matrix
167
168	You will be presented with a "Build Matrix".
169	The rows on the table represent an "Endpoint", like a webserver
170	or database server.
171
172	The columns of the table represent the "builds" or "codes" and where that
173	should go.
174	So if you are reading the table from left to right, the first row would
175	read something like:
176
177	"For my webserver (col. 1), I want my trunk code (col 2) to go to my
178	development server (col 3).".
179
180	You will notice in the drop downs that you can select any of the targets
181	and/or builds that you have created.
182
183	5) Click "Create Build Plan"
184
185	9. RUN A BUILDPLAN
186
187	Select the build plan you have just created by clicking "view" on the "Buildplan"
188	section of your AP.
189
190	From there, select what repository version you wish to use, and just click
191	"Run Build".