TextBook

From Textbook

Overview

This is a Subversion (SVN) command line approach for upgrading to the absolute latest revision of Textpattern for development testing of the Textpattern system (not live publication). This approach specifically uses Secure Shell (SSH), which allows for Secure Shell Tunneling. If you just want the latest stable release--recommended for live publishing--see the other instructions, Repo (Stable) to TxD Server via SSH (for Publishing).

A few things to note before diving in:

1. Instructions assume you already have Textpattern installed somewhere for development purposes, and you're simply updating to the latest development revision.
2. Instructions are written from a Windows XP perspective, but if your on Mac X you should be able to follow along in similar fashion with the appropriate terminal (maby not exactly).
3. Instructions are written for those hosted by TextDrive.
4. In addition to obtaining a SSH client, and depending on which TextDrive server you are on, you may also need to get a shell access to your TextDrive server. To get a shell access, you need to put in a support ticket with the TextDrive Help Desk (TextDrive servers known at this time that need a shell access are "one" and "barclay").

If you need a shell access to your TextDrive server, then you should stop now and take care of that before proceeding with these instructions. Note also that a shell access with TextDrive is not the same thing as having a SSH client, which is where these instructions begin.

Obtaining a Secure Shell (SSH) Client and Logging-In

The first thing you will need to do, if you have not already done so, is obtain an Secure Shell (SSH) client. For Windows there are two likely candidates: OpenSSH or PuTTY. These instructions are presented using PuTTY, but you should be able to do accomplish the same thing with OpenSSH in similar fashion.

1. Download the PuTTY SSH client to your desktop. A PuTTY executable icon will be added to your desktop (Figure 1).
   
   Figure 1: The PuTTY icon
2. Click the icon. The PuTTY Configuration window will appear (Figure 2). (Note: there does not seem to be any installation process with PuTTY, it just opens up and starts working, so if you do not want to have PuTTY in your desktop, you will have to manually move it somewhere for next time.)
   
   Figure 2: The PuTTY Configuration window
3. In the top section of the PuTTY Configuration window where it reads Specify your connection by host name or IP address, you can type in either your servername at TextDrive (i.e., servername.textdrive.com) or use the TextDrive server IP address (you should have received this when you received your initial email from TextDrive about account setup information). Make sure the SSH radio button is selected and then click the Open button at the bottom of the window.
   Note: you will get a PuTTY security alert saying that the server's rsa2 key fingerprint is not recognized in your registry, and you will be be asked what to do. You have to either say Yes or No to do anything at all; saying Yes will add the key to your saved -- and assumingly trusted -- connections where it will remain next time, saying No will use the key to connect to the server but only for this session. You can say "Yes" if you are certain your IP is correct. A PuTTY command window will become active (see Figure 3 below).
   
   Figure 3: The PuTTY command-line window showing login prompt.
4. The first thing you'll see at the left of the command prompt is login as:. Type in your username for your TextDrive account at the green command prompt.
5. The information will change to reflect your status; it should now look like something with the following pattern: "username@IPaddress's password". Type in your TextDrive password at the command prompt.
6. If you successfully login, the information will change again and you'll see some copyright information. You'll also see a new command line prompt that looks something like this...-bash-2.05b$. At the prompt, type in the following line replacing yourusername and yourserver accordingly:

   ssh yourusername@yourserver.textdrive.com

7. Depending on whether you said yes or no to the "trusted connection" inquiry in step 3 above, you may or may not get a message indicating the authenticity of your server can't be established and do you want to continue. If you do, type "Yes". Your unknown server connection will be permanently added to your connections list. PuTTY will also indicate that your IP connection was closed; this is a little confusing, but in fact you are still connected to the server and the continued presence of the "-bash-2.05b$" at the command prompt is proof of this.

Establishing the Initial Subversion Connection

At this point you have simply created a SSH tunnel connection to TextDrive with the PuTTY client. Now you need to initially setup the Subversion process.

1. Use either of the following to make sure you're where you think you are and get oriented...

   pwd

   or...

   ls

   Note:

   • The first will tell you where you are at via a path, which should be /home/yourusername/, where "username" is your TextDrive account username.
   • The second will list all the directories on the server at the level you are currently at, which should be root of your server account. One of the directories (the one in which your installation is installed somewhere) is public_html.
2. If your Textpattern is installed in your domain root, type the following and hit Enter...

   cd public_html

   If it's in a subdirectory, then type the following and hit Enter (where yoursubdirectory is the subdirectory location you want or have)...

   cd public_html/yoursubdirectory

Now you should be in the directory of the Textpattern site you want to update.

Initializing Subversion on a Development Site

When initializing Subversion for the first time with an existing site, it's not a bad idea to move a couple things aside to ensure you do not lose important files or custom modifications within them. This is not something you will always have to do, just this first time.

1. First, move your textpattern folder aside...

   mv textpattern textpattern-old

   If you have any custom mod_rewrite rules in your .htaccess file, then move it aside as well...

   mv .htaccess .htaccess-old

   Notes:

   • It is not necessary to move the .htaccess file if you have not added any custom rules to the file.
   • In case you noticed it earlier, and are concerned, the .htaccess file will not appear in the SSH client when you do a list directory (ls) command to view your directory contents; however the file is indeed there, which you can verify with a SFTP client.
   If you have added images in your Textpattern images folder then you might want to move that aside too (otherwise, ignore the images folder), type the following at the command prompt and hit Enter...

   mv images images-old

2. Now you are ready to check out the latest revision of Textpattern's development series using SVN, use the following...

   svn co http://textpattern.googlecode.com/svn/development/4.x .

   Reminder: This version of Textpattern is intended for beta testing new features and changes only. If you want to run a live (public) site safely, you should use the instructions, Repo (Stable) to TxD Server via SSH (for Publishing).
3. Now you need to recover the things you moved. First, retrieve your old config.php file from the old /textpattern/ directory...

   cp textpattern-old/config.php textpattern/

   If you moved your images folder, retrieve that as well...

   mv images-old images

4. Next, make sure the CHMOD permissions on your images folder is 777 so you can add images to it later; try doing that now by typing the following at the command prompt and hit Enter...

   chmod 777 images

   If that does not work for some reason, then you may need to open up a Secure File Transfer Protocol (SFTP) client (required for TextDrive servers) and change the CHMOD value that way.
5. Handling the .htaccess File:
   1. Check to see if you even have the .htaccess file in your install location. Because using the "ls" command will not reveal your .htaccess file in the SSH client, you will need to open an SFTP client and look at the directory contents that way.
   2. If you don't see the .htaccess file, you'll need to retrieve it from the source location using SFTP.
   3. Finally, if your old .htaccess file had custom modifications you want to retain (e.g., custom mod_rewrite), you will need to copy and paste those customizations from your old file to the top of the new one without overwriting the contents of the new files.

Once these files are in place you are then ready to initialize your new Textpattern site.

Finalizing the Upgrade Process

Now you will handle the finishing touches for your switch to subversion.

1. Open your Web browser and login to the admin area of your Textpattern installation. By doing this you automatically trigger Textpattern to fire-off a bunch of scripts that updates the MySQL database with the code of the latest Textpattern version. The first page you should be taken to is the Languages page, where you will need to update your preferred language (simply click the link where indicated in the languages list).
2. Go to the Diagnostics Subtab panel and check for any diagnostics that need addressed.

Removing Obsolete Files

If all has gone well up to this point, you will now have a number of old or obsolete files and folders in your install location that you can get rid of, though you can leave them alone too if you want. If you want to scrap them, use the following commands in your SSH client as suggested.

1. To remove any previously installed files, use...

   rm .htaccess-old

   or...

   rm -R textpattern-old

2. To remove the obsolete files installed from the SVN process, use...

   rm textpattern/config.php.default

3. Since setup-related files are now in their own folder (namely, /setup/), the folder and all its contained files should be deleted after udgrading Textpattern as a security precaution. You should be able to delete this folder (and contents) all at once using...

   rm -rf textpattern/setup/

Future Subversion Updates (much easier at this point)

1. Open your SSH client and login as needed.
2. Access the directory where you have Textpattern installed.
3. Run an SVN update...

   svn update

4. Login to your administration panel to initialize the updates. You should be automatically taken to the Manage Languages view of the Preferences Subtab panel. If you are already logged into your admin pages, then navigate to the Preferences subtab and click on the 'Manage Languages' link at the top. Look for the languages you have installed and make sure to update them.
   Note: Languages that you have installed, and which need updated should be distinguished in the list with an orange background.
5. Now you can remove the obsolete files as described in the previous section.