Migrating Servers

On occasion, you may want to move from one server to another. For example, you may be upgrading to a dedicated server or moving to a server with a different PHP deployment method. You can request a server migration at any time with the WebFaction control panel (Accounts ‣ Server migration). You can select the operating system and location of the destination server, as well as the migration path you want to use.

There are two migration methods. The first is to manually migrate from one server to another; you will receive one free week of service on the old server to give you time to complete the steps below. Alternatively, you can elect to let WebFaction migrate servers for you. In either case, you are responsible for verifying that the migration was completed successfully.

If you have elected to migrate servers yourself, there are a few steps and choices ahead of you. While the process may look daunting, it’s actually quite easy. All it requires is a little bit of planning and attention to detail.

Migrating Manually

There are two different procedures for migrating from one server to another yourself. The Simple Migration Guide minimizes the number of steps used to migrate, but you may incur some downtime as you move. The Advanced Migration Guide minimizes the duration of downtime with a more complex procedure. Choose a procedure based on your downtime requirements and the level of complexity with which you’re comfortable.

As always, consider contacting the WebFaction support team if you’re not clear on some particular step. The support team will be happy to provide guidance and assistance through this process.

Simple Migration Guide

This simplified migration guide minimizes the number of steps to migrate from one server to another. If you do not need to maximize the availability of your sites or you are uncomfortable working with DNS changes and your system’s hosts file, use this procedure.

Create Users

The first step in moving to a new server is to create on the destination server the same users that appear on the origin server. For each user on the origin machine, create an equivalent user on the destination machine.

Create Applications

The next step is to recreate applications on the destination server. For each application on the origin server (as noted by the Machine column), create a new application with the same name on the destination server.

Note

Some applications, such as WordPress, may not permit two applications to share the same name. If you encounter this during your migration, create an application with a different name, but remember to use the alternate name when importing database records and creating website entries.

Copy Files

The next step is to copy files from the origin server to the destination server. rsync makes this easy.

1. For each user on the origin server:
   1. Open an SSH session on the origin machine.
   2. Get a list of files to be copied. Enter rsync -nPaAz ~/ username@destination.webfaction.com:, where username is the current user name and destination is the name of the destination server, and press Enter. A list of files to be copied will appear; no files are copied at this time.
   3. Verify that the files to be copied are those you intended.
   4. Copy the files to the destination server. Enter rsync -PaAz ~/ username@destination.webfaction.com: (noting that the n switch has been omitted) and press Enter. The files will be copied. Depending on the number and size of the files to be copied, this process may take a few minutes to finish.
2. If applicable, verify that the permissions for your extra users are correct by accessing files with the new extra users you would expect to have access to. If needed, grant access to your extra users.

Copy Crontabs

If you have configured or modified your users’ crontabs, the contents of your users’ crontabs must be copied from the origin server to the destination server. For each user:

1. Open an SSH session on the origin server.
2. Export the contents of the crontab to a file. Enter crontab -l > username_cron, where username is the name of the current user and press Enter. A file, username_cron, will be created in the current directory.
3. Copy the file to the destination server. Enter scp username_cron username@destination.webfaction.com: and press Enter. The file is copied to the destination server.
4. Close the SSH session.
5. Open an SSH session on the destination server.
6. Import the crontab. Enter crontab username_cron and press Enter.

Create Databases and Database Users

The next step is to recreate the databases and their users on the destination server.

Many application installers create a database automatically. If you have successfully recreated these applications, their databases and users do not need to be duplicated manually.

For all other databases and users, you must recreate each yourself. For each database on the origin server, create a new database on the destination server. For each database user on the origin server, create a new user and grant permissions. Be sure to use the same database names and usernames on the destation server as those on the origin server.

Copy Database Records

Once the databases are set up to receive the data from the origin server, it’s time to to export the data from the origin server and import that data to the databases on the destination server.

1. Open an SSH session on the origin server.

2. For each MySQL database on the origin server, dump the contents of the database to a file. Enter mysqldump -u username database -p > database.sql, where:

   • database is the name of the database
   • username is the name of a user that owns or has permission to use the database

   and press Enter. A dump file, database.sql, is created in the current directory.

3. For each PostgreSQL database on the origin server, dump the contents of the database to a file. Enter pg_dump -U username -f database.sql database and press Enter. A dump file, database.sql is created in the current directory.

4. Copy the dump files to the destination server. Enter scp ./*.sql username@destination.webfaction.com: and press Enter. All .sql files are copied to the destination server.

5. Close the SSH session on the origin server.

6. Open an SSH session on the destination server.

7. For each MySQL database on the destination server, import the corresponding dump file. Enter mysql -u username -p -D database < database.sql and press Enter. The contents of the file are loaded into the specified database.

8. For each PostgreSQL database on the destination server, import the corresponding dump file. Enter psql -U username database < database.sql and press Enter. The contents of the file are loaded into the specified database.

Edit Website Records

The next step is to modify your website entries to use the applications on the destination server.

1. Log in to the control panel.
2. Click Domains / websites ‣ Websites. The list of websites appears.
3. Modify the site records. For each website entry on the origin server:
   1. Click the name of the website entry. The site’s details appear.
   2. In the Machine menu, click to select the destination server.
   3. For each application in the Contents section:
      1. Remove the origin server application. Click x. The application is removed from the list.
      2. Click Add an application ‣ Reuse an existing application. The Reuse an existing web app form appears.
      3. In the Application menu, click to select the destination server application. For example, if you removed my_wp - origin then click to select my_wp - destination.
      4. In the URL field, enter the same URL as the origin server application’s URL.
      5. Click the Save button.
   4. Click the Save button.

Finishing Touches

Now that you have verified your destination server is operating smoothly, it is time to make any last minute updates, and clean up.

1. If needed, copy any new files or migrate any new data from the origin server to the destination server.
2. Reply to your existing support ticket (or open a new ticket) to inform the support team that your migration is complete and you’re ready for your data to be deleted on the origin server.

Congratulations, you have successfully migrated from one server to another.

Advanced Migration Guide

This advanced version of the migration process minimizes downtime at the expense of added complexity. Use this procedure if you need to maximize the availability of your sites and applications and you are comfortable working with DNS changes and your system’s hosts file.

Create Users

The first step in moving to a new server is to create on the destination server the same users that appear on the origin server. For each user on the origin machine, create an equivalent user on the destination machine.

Create Applications

The next step is to recreate applications on the destination server. For each application on the origin server (as noted by the Machine column), create a new application with the same name on the destination server.

Note

Some applications, such as WordPress, may not permit two applications to share the same name. If you encounter this during your migration, create an application with a different name, but remember to use the alternate name when importing database records and creating website entries.

Copy Files

The next step is to copy files from the origin server to the destination server. rsync makes this easy.

1. For each user on the origin server:
   1. Open an SSH session on the origin machine.
   2. Get a list of files to be copied. Enter rsync -nPaAz ~/ username@destination.webfaction.com:, where username is the current user name and destination is the name of the destination server, and press Enter. A list of files to be copied will appear; no files are copied at this time.
   3. Verify that the files to be copied are those you intended.
   4. Copy the files to the destination server. Enter rsync -PaAz ~/ username@destination.webfaction.com: (noting that the n switch has been omitted) and press Enter. The files will be copied. Depending on the number and size of the files to be copied, this process may take a few minutes to finish.
2. If applicable, verify that the permissions for your extra users are correct by accessing files with the new extra users you would expect to have access to. If needed, grant access to your extra users.

Copy Crontabs

If you have configured or modified your users’ crontabs, the contents of your users’ crontabs must be copied from the origin server to the destination server. For each user:

1. Open an SSH session on the origin server.
2. Export the contents of the crontab to a file. Enter crontab -l > username_cron, where username is the name of the current user and press Enter. A file, username_cron, will be created in the current directory.
3. Copy the file to the destination server. Enter scp username_cron username@destination.webfaction.com: and press Enter. The file is copied to the destination server.
4. Close the SSH session.
5. Open an SSH session on the destination server.
6. Import the crontab. Enter crontab username_cron and press Enter.

Create Databases and Database Users

The next step is to recreate the databases and their users on the destination server.

Many application installers create a database automatically. If you have successfully recreated these applications, their databases and users do not need to be duplicated manually.

For all other databases and users, you must recreate each yourself. For each database on the origin server, create a new database on the destination server. For each database user on the origin server, create a new user and grant permissions. Be sure to use the same database names and usernames on the destation server as those on the origin server.

Copy Database Records

Once the databases are set up to receive the data from the origin server, it’s time to to export the data from the origin server and import that data to the databases on the destination server.

1. Open an SSH session on the origin server.

2. For each MySQL database on the origin server, dump the contents of the database to a file. Enter mysqldump -u username database -p > database.sql, where:

   • database is the name of the database
   • username is the name of a user that owns or has permission to use the database

   and press Enter. A dump file, database.sql, is created in the current directory.

3. For each PostgreSQL database on the origin server, dump the contents of the database to a file. Enter pg_dump -U username -f database.sql database and press Enter. A dump file, database.sql is created in the current directory.

4. Copy the dump files to the destination server. Enter scp ./*.sql username@destination.webfaction.com: and press Enter. All .sql files are copied to the destination server.

5. Close the SSH session on the origin server.

6. Open an SSH session on the destination server.

7. For each MySQL database on the destination server, import the corresponding dump file. Enter mysql -u username -p -D database < database.sql and press Enter. The contents of the file are loaded into the specified database.

8. For each PostgreSQL database on the destination server, import the corresponding dump file. Enter psql -U username database < database.sql and press Enter. The contents of the file are loaded into the specified database.

Reconfigure DNS

Now it is time to begin creating the environment to test the applications on your migrated server. To create this environment, the DNS records for your domains must be changed such that the destination server will not be used to serve pages and data until they are ready.

For each domain in use by the existing (origin server) websites, configure an A record such that the IP address of the A record is set to the IP address of the origin server.

Note

To find the IP address of the origin server:

1. Log in to the WebFaction control panel.
2. Click Account ‣ Dashboard.
3. Review the Settings section.

Create Website Records

The next step is to recreate your website entries.

1. Log in to the WebFaction control panel.
2. Click Domains / websites ‣ Websites. The list of websites appears.
3. For each website entry on the origin server, create a new website entry with the same settings, except for these differences:
   • in the Name field, enter a unique name;
   • in the Machine field, click to select the destination server;
   • each application added to the site must be the migrated application on the destination server. For example, if my_wp - origin were in use in the origin server’s website record, use my_wp - destination where destination and origin are the destination and origin servers, respectively.

Test Your Migrated Applications

Now it is time to verify that everything on the new server is working correctly. Because of the DNS changes made previously, you must reconfigure your computer to use the destination server instead of the origin server for each of your domains.

Warning

Always create a backup before modifying system files.

1. Open your hosts file in a text editor. Different operating systems store this file in different locations:

   • Windows: %SystemRoot%\system32\drivers\etc\ (typically, c:\windows\system32\drivers\etc\)
   • Mac OS X: /private/etc/hosts/ or /etc/hosts/
   • Linux: /etc/hosts

2. For each A record you made previously, add this line to the file:

   1.2.3.4 example.com

   where 1.2.3.4 is the IP address of the destination server and example.com is the domain for which you created the A record.

3. Save and close the file.

Now you can access your websites as they will appear on the destination server. Take the time to verify that each application works as you expect it to. If needed, make any necessary configuration changes to make your new applications work. For example, you may need to update the port number used in conjunction with custom applications listening on a port.

Only when you are confident the applications on the destination server are working properly should you move on to the next phase of migration.

Warning

Once you’re finished testing, don’t forget to revert the changes made to your hosts file.

Direct Traffic to the New Server

To direct incoming traffic to the destination server, you must revert the DNS changes made previously. To remove the DNS changes:

1. Log in to the WebFaction control panel.
2. Click Domains / websites ‣ Domains. The list of domains appears.
3. For each domain in use by the origin server websites:
   1. Click on the domain name. The domain’s settings appear.
   2. In the Hosting section, click to select WebFaction.
   3. Click the Save button.

Next, wait until all incoming traffic has switched to the new server. Because of DNS propagation, it may take up to 48 hours for all incoming requests to move to the new server. You can confirm incoming traffic is limited to the new server by reviewing the origin server log files.

Delete Origin Server Website Records

To switch over to the new applications on your destination server, delete the website records associated with the origin server. Now you can access your sites and applications on the new server. Make sure everything is working as expected before moving on.

Finishing Touches

Now that you have verified your destination server is operating smoothly, it is time to make any last minute updates, and clean up.

1. If needed, copy any new files or migrate any new data from the origin server to the destination server.
2. Reply to your existing support ticket (or open a new ticket) to inform the support team that your migration is complete and you’re ready for your data to be deleted on the origin server.

Congratulations, you have successfully migrated from one server to another.

Migrating from a CentOS 5 (32-bit) Server to a Centos 6 (64-bit) Server

If you’re migrating from a 32-bit CentOS 5 server to a 64-bit CentOS 6 server, binaries compiled for the CentOS 5 32-bit server will generally not work on the CentOS 6 64-bit server. This means that many compiled binaries on the originating server must be recompiled on the destination server.

Many common applications, such as WordPress, Subversion, Static-only and Static/CGI/PHP applications, will work properly without any additional steps, but others may require changes. The following sections contain directions for migrating these application types.

Django

Django applications require a binary and libraries compiled for the destination server after migration (otherwise, an error while loading shared libraries error will occur). To finish a Django application migration:

1. Create an additional Django application of the same version as the migrated application.
2. Update the Django application’s binary and libraries.
   1. Open an SSH session to your account on the destination server.
   2. Copy the Apache HTTP Server binaries from the additional Django application to the migrated application. Enter cp $HOME/webapps/additional/apache2/bin/httpd* $HOME/webapps/migrated/apache2/bin/, where additional is the additional Django application and migrated is the migrated Django application and press Enter.
   3. Copy the contents of the additional Django application’s modules directory to the migrated Django application’s modules directory. Enter cp $HOME/webapps/additional/apache2/modules/* $HOME/webapps/migrated/apache2/modules/ and press Enter.
   4. Restart the migrated Django application. Enter $HOME/webapps/migrated/apache2/bin/restart and press Enter.
3. Verify that your Django application is now running properly.
4. Remove the additional Django application.

Rails

Rails applications require a binary and libraries compiled for the destination server after migration (otherwise, an error while loading shared libraries error will occur). To finish migrating a Rails application to a CentOS 6 server:

1. Create an additional Rails application of the same version as the migrated application.
2. Update the Rails application’s binary and libraries.
   1. Open an SSH session to your account on the destination server.
   2. Copy the nginx file from the additional Rails application to the migrated application. Enter cp $HOME/webapps/additional/nginx/sbin/nginx $HOME/webapps/migrated/nginx/sbin/nginx, where additional is the additional Rails application and migrated is the migrated Rails application and press Enter.
   3. Copy the contents of the additional Rails application’s gems directory to the migrated Rails application’s gems directory. Enter cp -R $HOME/webapps/additional/gems/* $HOME/webapps/migrated/gems/ and press Enter.
   4. Restart the migrated Rails application. Enter $HOME/webapps/migrated/bin/restart and press Enter.
3. Verify that your Rails application is now running properly.
4. Remove the additional Rails application.

Trac

Migrated Trac applications must be switched over to a newer version of Python for continued Subversion integration (otherwise, a Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn) error will occur). To finish migrating a Trac application to a CentOS 6 server:

1. Modify the Trac application’s CGI file to use Python 2.6.
   1. Open $HOME/webapps/tracapp/cgi-bin/trac.cgi, where tracapp is the name of the Trac application, in a text editor.
   2. Change the first line of the file from #!/usr/local/bin/python2.4 to #!/usr/local/bin/python2.6.
   3. Save and close the file.
2. Move the Trac application’s libraries the new required location.
   1. Open an SSH session to your account on the destination server.
   2. Remove the symbolic link to the Trac static assets. Enter rm $HOME/webapps/tracapp/htdocs and press Enter.
   3. Move the Trac libraries. Enter mv $HOME/webapps/tracapp/lib/python2.4 $HOME/webapps/tracapp/lib/python2.6 and press Enter
   4. Recreate the symbolic link to the Trac static assets. Enter ln -s $HOME/webapps/tracapp/lib/python2.6/Trac-0.12-py2.4.egg/trac/htdocs $HOME/webapps/tracapp/htdocs and press Enter.

Zope and Plone

Zope and Plone applications require Python to be compiled for the destination server after migration, otherwise error while loading shared libraries or wrong ELF class errors will occur. To finish migrating a Zope application to a CentOS 6 server:

1. Create an additional Zope application of the same version as the migrated application.
2. Update the Zope application’s libraries.
   1. Open an SSH session to your account on the destination server.
   2. Copy the contents of the additional Zope application’s Python-2.6 directory to the migrated Zope application’s Python-2.6 directory. Enter cp -R $HOME/webapps/additional/Python-2.6/* $HOME/webapps/migrated/Python-2.6/ where additional is the name of the additional Zope application and migrated is the name of the migrated Zope application and press Enter.
   3. Restart the Zope application. Enter $HOME/webapps/migrated/zinstance/bin/instance restart and press Enter.
3. Verify that your Zope application is now running properly.
4. Remove the additional Zope application.