How to migrate your Joomla site to a new server using an Akeeba backup archive.
These notes assume you have installed Akeeba Backup on the old server and used it to create a backup archive. If you are transferring your site to a new web host, see also the Joomla installation notes.
COPY BACKUP TO STORAGE OR NEW SERVER
If you wish to transfer the backup from one server to another, save time and copy it directly between the servers. Determine the location of the backup on the old server; see Components – Akeeba Backup – Options – Basic – Output Directory. Using SSH, log in to the new server, cd to the destination directory, and using scp:
scp firstname.lastname@example.org:/full/path/to/backup_file.jpa .
Notice the trailing dot.
Some servers don’t seem to want to accept incoming scp connections, so if this fails you can try it the other way around, logging into the old server and scp from it into the new server:
scp backup_file.jpa email@example.com:/full/path/to/destination/directory/
If the backup is for a new installation, be it local or remote, see the “Preparation” section of the Joomla installation notes for important advice.
EXTRACT BACKUP ONTO NEW SERVER
There are two ways to proceed: the easy way and the manual way. Try the easy way first. If you run into insurmountable problems, blow away the extracted files and try the manual way.
Whichever way you choose, you need to have previously created an empty database on the new server. The installer does not create a database.
The easy way
Download the latest stable version of Akeeba Kickstart. Unpack it and upload the file kickstart.php to the same directory the backup was copied to. The other files in the Kickstart package are localizations and can be discarded. Point your browser to “http://newserver.com/kickstart.php“, change any settings as desired (default settings are usually fine) and click “Start”.
If Kickstart fails stating that it is unable to extract directories, change the permissions of the installation directory to 777. Remember to change this back to the previous setting when finished.
Kickstart will extract the backup file onto the new server and prompt you to begin the installer. Before doing so, inspect the installed files with SSH or FTP and confirm that ownership and permissions are correct. Ideally, ownership should be username:users, file permissions 644, and directory permissions 755. Correct if needed.
If you are unable to correct — perhaps ownership is set to “nobody” or files are otherwise not writable by you — then something fundamental is wrong with permissions or CGI wrapping. Stop, correct the issue, and start over.
The manual way
SSH in to the new server, cd to the web server docroot, and:
mv .htaccess .htaccess-old unzip backup_file.zip rm backup_file.zip ls -la
Review file ownership and permissions, and change as needed.
Review .htaccess and .htaccess-old, and edit the new .htaccess as needed. Delete .htaccess-old.
Edit the configuration.php file found in the server docroot. Similarly named files, such as configuration.php-dist, may be ignored. Inspect the file for variables from the old server need to be updated. Variables I have changed include:
$host = 'database_server_name'; $user = 'database_user_with_full_privileges'; $password = 'database_password'; $db = 'database_name'; $live_site = 'http://188.8.131.52/'; # The IP address of the new server $secret = ''; # A random alphanumeric string; TODO: Document this $log_path = '../logs'; # Path to logs; TODO: Document this $tmp_path = '../tmp'; # Path to temp directory; TODO: Document this
$host is the database server name. Often this is ‘localhost’. Other values to try are the database server name as shown in phpMyAdmin or your web server’s name. If the value of $host is wrong, attempting to view the site will fail with the error message “Database connection error (3): Could not connect to database”.
A similar error message, “Database connection error (2): Could not connect to MySQL,” indicates that $user, $password, or $db are incorrect. Check your work and try again.
On the old server, the value of $live_site is of the form http://www.example.com/. Until the nameservers are re-pointed the domain name will not work on the new server, so for now use the new server’s IP address. If the Joomla docroot is a subdirectory of the new server’s docroot, also provide the path to it (e.g. http://184.108.40.206/subdirectory/). Once the nameservers are re-pointed and propagated, best practice is to change this variable back to the domain name.
$secret is a random alphanumeric string and should be changed when a site is moved to a new server. TODO: Document what this is for.
Save your changes to the new server.
If you have the file .htaccess, rename it to something else before continuing. Remember to rename it back to .htaccess when you finish installing.
Point your browser to “http://newserver.com/index.php” to begin the installer.
INSTALL THE BACKUP ON THE NEW SERVER
Follow the on-screen instructions to open the installer and proceed.
You will have the chance to change permissions on the installed directories and files.
When the Akeeba Installer is done, it prompts you to delete the installation directory. Ignore this prompt and simply close the window. Back to the Kickstart window, click the second link titled “here”.
Once the backup has been installed on the new server, follow the checklist in “Configuration: What You Must Do” in the Joomla installation notes. You may also consider items in “Configuration: What You May Want To Do”. If you excluded cache/ and tmp/ from backups when setting up Akeeba as I recommended above, you will find that they have not been created on the new server. Go ahead and create them manually, using the normal permissions of 755.
Take the site online in Site – Global Configuration – Site.
Akeeba Backup Core is available at no cost and depends upon donations from users to sustain the project. If you find it useful, please consider purchasing the Professional version or donating to the project.