profiles/hostmaster/UPGRADE.txt

.. This document is formatted using the ReST syntax.

==========================
Aegir Upgrade Instructions
==========================

-----------------------------------------------------------------------------
This document describes briefly how to upgrade an existing Aegir installation
-----------------------------------------------------------------------------

Conventions and tips
====================

All instructions and in general all commands must be run as aegir user,
so all permissions are always set correctly.

To become aegir user you can issue this command::

  su -s /bin/sh aegir

(Note you must run this as root or prefix with sudo).

Note that /bin/sh is an example. You may wish to instead use the shell
of your choice, i.e /bin/bash

Additionally to make following instructions generic and not dependant on
a concrete Drupal or Aegir version, we will use shell environment
variables. So current Drupal is 6.14 and Aegir release is 0.4-alpha2. We
assume we are upgrading from a Drupal 6.13.

You should replace following command for current versions at the time
you are reading this document.

Shell commands::

  export DRUPAL_DIR=/var/aegir/drupal-6.14
  export OLD_DRUPAL_DIR=/var/aegir/drupal-6.13
  export AEGIR_TAG=DRUPAL-6--0-4-ALPHA2

This document also assumes drush is installed properly and we use a
environment variable to simplify the documentation again.

Shell commands::

  export DRUSH='php /var/aegir/drush/drush.php'

Finally, we use CVS to install some packages, so this needs to be
installed for upgrades. On Debian, this means:

Shell commands::

 apt-get install cvs

Generic upgrade instructions
============================

We aim to create a generic upgrade process that will be consistent
across versions. This section describes this process. However, there
are version-specific upgrade instructions that may be more relevant to
your installation in the next section.

Upgrading the backend
---------------------

In general, we try to keep the backend and the frontend compatible
with each other during release cycles. That is: provision 0.3 and
hosting 0.3 will always be able to talk to each other. hosting 0.2 was
able to talk to provision 0.3 too, but the API is not well enough
defined so that can be counted upon.

Therefore, you want to keep the frontend and the backend in sync. When
you do a major upgrade (e.g. 0.2 -> 0.3) of the backend, you *must*
upgrade the frontend soon after.

Bottomline: first you upgrade the backend, then the frontend.

Upgrading the backend is as simple as installing a new version of
Drush and Provision over the old ones. Follow the instructions in
INSTALL.txt for that. Keep a copy of the old provision and drush in
case something goes wrong in the frontend.

Upgrading the frontend
----------------------

Those are generic instructions to upgrade your hosting, hostmaster,
eldir or Drupal core installation to new versions. This is still a
delicate operation but has been known to work between 0.2 and 0.3 (see
below for 0.2-specific instructions) and upgrades between 0.3
development milestones.

This document suggests using provision to upgrade the frontend, so
it's a bit more tricky than with a usual site because you cannot (yet)
use the regular frontend to drive the backend. So you need to go
through some extra steps and the commandline to upgrade Aegir.

The generic upgrade mechanism is to this:

 * backup the site
 * deploy to a test site
 * verify if it works
 * delete the old site
 * delpoy to new site

We use backup and deploy because a "migrate" is likely to fail and
want to test the new site first.

Note that this assumes you have already updated provision to a proper
version, see above.

Shell commands::

 cd /var/aegir
 $DRUSH dl drupal
 cd $DRUPAL_DIR
 export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
 cvs co -d profiles/hostmaster -r$AEGIR_TAG contributions/profiles/hostmaster
 mkdir profiles/hostmaster/modules profiles/modules/themes
 $DRUSH dl --destination=./profiles/hostmaster/modules hosting install_profile_api
 $DRUSH dl --destination=./profiles/hostmaster/themes eldir 
 # also checkout any modules you may have enabled in the old platform
 #
 # now you want to add the new platform in the frontend (Create
 # content -> platform) and wait for the task to be processed
 $DRUSH -r $OLD_DRUPAL_DIR provision backup aegir.example.com ~/aegir.tar.gz
 $DRUSH -r $DRUPAL_DIR provision verify
 $DRUSH -r $DRUPAL_DIR provision deploy d6.aegir.example.com ~/aegir.tar.gz
 # review changes, see if it works to your liking, when you're done
 $DRUSH -r $DRUPAL_DIR provision delete d6.aegir.example.com
 crontab -e # disable the cronjob to avoid warnings
 $DRUSH -r $OLD_DRUPAL_DIR provision delete aegir.example.com
 # here you should really use the backup generated in the above step,
 # but the old backups also works, it's just not up to date
 $DRUSH -r $DRUPAL_DIR provision deploy aegir.example.com ~/aegir.tar.gz
 crontab -e # change platform path to $DRUPAL_DIR

Specific upgrade procedures
===========================

This section describes specific upgrade steps that must be taken
between certain point releases. If one of those section applies to
your installation, disregard the generic instructions and use those.

Upgrading the frontend from 0.2 (Drupal 5)
------------------------------------------

The major change between 0.3 and 0.2 is that 0.3 now targets the
Drupal 6 platform on the frontend (note the backend still supports
both Drupal 5 and 6).We also switch away from using the sites/default/
for Aegir in 0.3. So the upgrade procedure is basically the "Upgrading
the Drupal core safely" procedure detailed above, with some extra
steps.

Make sure you also checkout the install_profile_api module (>=2.1) as
it is a new dependency.

The first step is to import and verify the current aegir site
(sites/default) so it has a proper configuration. This needs to be
done because the default site was completely ignored by Aegir up until
now and needs to be transfered now.

In this case, the old drupal is a drupal 5:

Shell commands::

  export DRUPAL_DIR=/var/aegir/drupal-6.13
  export OLD_DRUPAL_DIR=/var/aegir/drupal-5.9

Note that this assumes you have already updated provision to a proper
version, see above.

Shell commands::

 cd /var/aegir
 $DRUSH dl drupal
 cd $DRUPAL_DIR
 cvs co -d profiles/hostmaster -r$AEGIR_TAG contributions/profiles/hostmaster
 mkdir profiles/hostmaster/modules
 $DRUSH dl --destination=./profiles/hostmaster/modules hosting install_profile_api
 $DRUSH dl --destination=./profiles/hostmaster/themes eldir 
 # also checkout any modules you may have enabled in the d5 platform
 # now you want to add the platform in the frontend (Create content -> platform) and wait for the task to be processed
 $DRUSH -r $OLD_DRUPAL_DIR provision verify
 $DRUSH -r $OLD_DRUPAL_DIR provision import default
 $DRUSH -r $OLD_DRUPAL_DIR provision verify default
 $DRUSH -r $OLD_DRUPAL_DIR provision backup default ~/default.tar.gz
 $DRUSH -r $DRUPAL_DIR provision verify
 $DRUSH -r $DRUPAL_DIR provision deploy d6.aegir.example.com ~/default.tar.gz
 # review changes, see if it works to your liking, when you're done:
 $DRUSH -r $DRUPAL_DIR provision delete d6.aegir.example.com
 crontab -e # disable the cronjob to avoid warnings
 $DRUSH -r $OLD_DRUPAL_DIR provision delete aegir.example.com
 # here you should really use the backup generated in the above step,
 # but the old backups also works, it's just not up to date
 $DRUSH -r $DRUPAL_DIR provision deploy aegir.example.com ~/default.tar.gz
 crontab -e # change root to new platform, make sure you have a --uri=aegir.example.com

Note that the import/verify of the 'default' site is required only
because that site is typically ignored in Aegir. This procedure will
migrate your main frontend away from that 'default' setup. See
http://drupal.org/node/453540 for details.

Upgrading Aegir from 0.1
------------------------

Note: to upgrade from 0.1 to 0.3, it is highly recommended that you
first upgrade to 0.2.

Upgrading hostmaster should be as simple as removing the provision and
drush modules from your profiles/hostmaster/modules directory. You
also need to create a new drush and provision checkout. Finally, you
can remove the drush.php symlink.

You will also need to update the hosting module and run update.php so
that new changes to the database are taken into account. This will
trigger platform verification and other cleanup tasks. Starting with
0.2, this process will be automated (see the above process).

Finally, you will need to put the path to that new drush in the
webserver node configuration. Rerunning the wizard will prompt you for
that. Make sure you also run the hosting setup command.

Those commands need to be ran as your "aegir" user.

Shell commands::

 export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
 cd /var/aegir
 cvs co -d drush -rDRUPAL-6--2-1 contributions/modules/drush
 mkdir .drush
 cvs co -d .drush/provision -rDRUPAL-6--0-2 contributions/modules/provision
 rm drupal-5.x/drush.php
 rm -r drupal-5.x/profiles/hostmaster/modules/provision
 rm -r drupal-5.x/profiles/hostmaster/modules/drush
 cvs up -A drupal-5.x/profiles/hostmaster/modules/hosting
 # here run update.php on the site and setup your drush path
 cd drupal-5.x && php ../drush/drush.php hosting setup

Upgrading Hostslave platforms from 0.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Provision has been migrated out of the platforms. It used to be
installed in the profiles/hostslave/modules directory. It is now in
~/.drush/provision. So you can simply cleanup the hostslave profile
and the virtual host created for the hostslave profile. You can also
remove the drush symlink.

Shell commands::

 cd /var/aegir
 rm -r drupal-6.x/profiles/hostslave
 rm config/vhost.d/hostslave
 rm drupal-6.x/drush.php

You should also delete the database created during the hostslave
install:

SQL commands::

 DROP DATABASE hostslave;
1	.. This document is formatted using the ReST syntax.
2
3	==========================
4	Aegir Upgrade Instructions
5	==========================
6
7	-----------------------------------------------------------------------------
8	This document describes briefly how to upgrade an existing Aegir installation
9	-----------------------------------------------------------------------------
10
11	Conventions and tips
12	====================
13
14	All instructions and in general all commands must be run as aegir user,
15	so all permissions are always set correctly.
16
17	To become aegir user you can issue this command::
18
19	su -s /bin/sh aegir
20
21	(Note you must run this as root or prefix with sudo).
22
23	Note that /bin/sh is an example. You may wish to instead use the shell
24	of your choice, i.e /bin/bash
25
26	Additionally to make following instructions generic and not dependant on
27	a concrete Drupal or Aegir version, we will use shell environment
28	variables. So current Drupal is 6.14 and Aegir release is 0.4-alpha2. We
29	assume we are upgrading from a Drupal 6.13.
30
31	You should replace following command for current versions at the time
32	you are reading this document.
33
34	Shell commands::
35
36	export DRUPAL_DIR=/var/aegir/drupal-6.14
37	export OLD_DRUPAL_DIR=/var/aegir/drupal-6.13
38	export AEGIR_TAG=DRUPAL-6--0-4-ALPHA2
39
40	This document also assumes drush is installed properly and we use a
41	environment variable to simplify the documentation again.
42
43	Shell commands::
44
45	export DRUSH='php /var/aegir/drush/drush.php'
46
47	Finally, we use CVS to install some packages, so this needs to be
48	installed for upgrades. On Debian, this means:
49
50	Shell commands::
51
52	apt-get install cvs
53
54	Generic upgrade instructions
55	============================
56
57	We aim to create a generic upgrade process that will be consistent
58	across versions. This section describes this process. However, there
59	are version-specific upgrade instructions that may be more relevant to
60	your installation in the next section.
61
62	Upgrading the backend
63	---------------------
64
65	In general, we try to keep the backend and the frontend compatible
66	with each other during release cycles. That is: provision 0.3 and
67	hosting 0.3 will always be able to talk to each other. hosting 0.2 was
68	able to talk to provision 0.3 too, but the API is not well enough
69	defined so that can be counted upon.
70
71	Therefore, you want to keep the frontend and the backend in sync. When
72	you do a major upgrade (e.g. 0.2 -> 0.3) of the backend, you must
73	upgrade the frontend soon after.
74
75	Bottomline: first you upgrade the backend, then the frontend.
76
77	Upgrading the backend is as simple as installing a new version of
78	Drush and Provision over the old ones. Follow the instructions in
79	INSTALL.txt for that. Keep a copy of the old provision and drush in
80	case something goes wrong in the frontend.
81
82	Upgrading the frontend
83	----------------------
84
85	Those are generic instructions to upgrade your hosting, hostmaster,
86	eldir or Drupal core installation to new versions. This is still a
87	delicate operation but has been known to work between 0.2 and 0.3 (see
88	below for 0.2-specific instructions) and upgrades between 0.3
89	development milestones.
90
91	This document suggests using provision to upgrade the frontend, so
92	it's a bit more tricky than with a usual site because you cannot (yet)
93	use the regular frontend to drive the backend. So you need to go
94	through some extra steps and the commandline to upgrade Aegir.
95
96	The generic upgrade mechanism is to this:
97
98	* backup the site
99	* deploy to a test site
100	* verify if it works
101	* delete the old site
102	* delpoy to new site
103
104	We use backup and deploy because a "migrate" is likely to fail and
105	want to test the new site first.
106
107	Note that this assumes you have already updated provision to a proper
108	version, see above.
109
110	Shell commands::
111
112	cd /var/aegir
113	$DRUSH dl drupal
114	cd $DRUPAL_DIR
115	export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
116	cvs co -d profiles/hostmaster -r$AEGIR_TAG contributions/profiles/hostmaster
117	mkdir profiles/hostmaster/modules profiles/modules/themes
118	$DRUSH dl --destination=./profiles/hostmaster/modules hosting install_profile_api
119	$DRUSH dl --destination=./profiles/hostmaster/themes eldir
120	# also checkout any modules you may have enabled in the old platform
121	#
122	# now you want to add the new platform in the frontend (Create
123	# content -> platform) and wait for the task to be processed
124	$DRUSH -r $OLD_DRUPAL_DIR provision backup aegir.example.com ~/aegir.tar.gz
125	$DRUSH -r $DRUPAL_DIR provision verify
126	$DRUSH -r $DRUPAL_DIR provision deploy d6.aegir.example.com ~/aegir.tar.gz
127	# review changes, see if it works to your liking, when you're done
128	$DRUSH -r $DRUPAL_DIR provision delete d6.aegir.example.com
129	crontab -e # disable the cronjob to avoid warnings
130	$DRUSH -r $OLD_DRUPAL_DIR provision delete aegir.example.com
131	# here you should really use the backup generated in the above step,
132	# but the old backups also works, it's just not up to date
133	$DRUSH -r $DRUPAL_DIR provision deploy aegir.example.com ~/aegir.tar.gz
134	crontab -e # change platform path to $DRUPAL_DIR
135
136	Specific upgrade procedures
137	===========================
138
139	This section describes specific upgrade steps that must be taken
140	between certain point releases. If one of those section applies to
141	your installation, disregard the generic instructions and use those.
142
143	Upgrading the frontend from 0.2 (Drupal 5)
144	------------------------------------------
145
146	The major change between 0.3 and 0.2 is that 0.3 now targets the
147	Drupal 6 platform on the frontend (note the backend still supports
148	both Drupal 5 and 6).We also switch away from using the sites/default/
149	for Aegir in 0.3. So the upgrade procedure is basically the "Upgrading
150	the Drupal core safely" procedure detailed above, with some extra
151	steps.
152
153	Make sure you also checkout the install_profile_api module (>=2.1) as
154	it is a new dependency.
155
156	The first step is to import and verify the current aegir site
157	(sites/default) so it has a proper configuration. This needs to be
158	done because the default site was completely ignored by Aegir up until
159	now and needs to be transfered now.
160
161	In this case, the old drupal is a drupal 5:
162
163	Shell commands::
164
165	export DRUPAL_DIR=/var/aegir/drupal-6.13
166	export OLD_DRUPAL_DIR=/var/aegir/drupal-5.9
167
168	Note that this assumes you have already updated provision to a proper
169	version, see above.
170
171	Shell commands::
172
173	cd /var/aegir
174	$DRUSH dl drupal
175	cd $DRUPAL_DIR
176	cvs co -d profiles/hostmaster -r$AEGIR_TAG contributions/profiles/hostmaster
177	mkdir profiles/hostmaster/modules
178	$DRUSH dl --destination=./profiles/hostmaster/modules hosting install_profile_api
179	$DRUSH dl --destination=./profiles/hostmaster/themes eldir
180	# also checkout any modules you may have enabled in the d5 platform
181	# now you want to add the platform in the frontend (Create content -> platform) and wait for the task to be processed
182	$DRUSH -r $OLD_DRUPAL_DIR provision verify
183	$DRUSH -r $OLD_DRUPAL_DIR provision import default
184	$DRUSH -r $OLD_DRUPAL_DIR provision verify default
185	$DRUSH -r $OLD_DRUPAL_DIR provision backup default ~/default.tar.gz
186	$DRUSH -r $DRUPAL_DIR provision verify
187	$DRUSH -r $DRUPAL_DIR provision deploy d6.aegir.example.com ~/default.tar.gz
188	# review changes, see if it works to your liking, when you're done:
189	$DRUSH -r $DRUPAL_DIR provision delete d6.aegir.example.com
190	crontab -e # disable the cronjob to avoid warnings
191	$DRUSH -r $OLD_DRUPAL_DIR provision delete aegir.example.com
192	# here you should really use the backup generated in the above step,
193	# but the old backups also works, it's just not up to date
194	$DRUSH -r $DRUPAL_DIR provision deploy aegir.example.com ~/default.tar.gz
195	crontab -e # change root to new platform, make sure you have a --uri=aegir.example.com
196
197	Note that the import/verify of the 'default' site is required only
198	because that site is typically ignored in Aegir. This procedure will
199	migrate your main frontend away from that 'default' setup. See
200	http://drupal.org/node/453540 for details.
201
202	Upgrading Aegir from 0.1
203	------------------------
204
205	Note: to upgrade from 0.1 to 0.3, it is highly recommended that you
206	first upgrade to 0.2.
207
208	Upgrading hostmaster should be as simple as removing the provision and
209	drush modules from your profiles/hostmaster/modules directory. You
210	also need to create a new drush and provision checkout. Finally, you
211	can remove the drush.php symlink.
212
213	You will also need to update the hosting module and run update.php so
214	that new changes to the database are taken into account. This will
215	trigger platform verification and other cleanup tasks. Starting with
216	0.2, this process will be automated (see the above process).
217
218	Finally, you will need to put the path to that new drush in the
219	webserver node configuration. Rerunning the wizard will prompt you for
220	that. Make sure you also run the hosting setup command.
221
222	Those commands need to be ran as your "aegir" user.
223
224	Shell commands::
225
226	export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
227	cd /var/aegir
228	cvs co -d drush -rDRUPAL-6--2-1 contributions/modules/drush
229	mkdir .drush
230	cvs co -d .drush/provision -rDRUPAL-6--0-2 contributions/modules/provision
231	rm drupal-5.x/drush.php
232	rm -r drupal-5.x/profiles/hostmaster/modules/provision
233	rm -r drupal-5.x/profiles/hostmaster/modules/drush
234	cvs up -A drupal-5.x/profiles/hostmaster/modules/hosting
235	# here run update.php on the site and setup your drush path
236	cd drupal-5.x && php ../drush/drush.php hosting setup
237
238	Upgrading Hostslave platforms from 0.1
239	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240
241	Provision has been migrated out of the platforms. It used to be
242	installed in the profiles/hostslave/modules directory. It is now in
243	~/.drush/provision. So you can simply cleanup the hostslave profile
244	and the virtual host created for the hostslave profile. You can also
245	remove the drush symlink.
246
247	Shell commands::
248
249	cd /var/aegir
250	rm -r drupal-6.x/profiles/hostslave
251	rm config/vhost.d/hostslave
252	rm drupal-6.x/drush.php
253
254	You should also delete the database created during the hostslave
255	install:
256
257	SQL commands::
258
259	DROP DATABASE hostslave;