Installation Instructions

Instructions for the installation of the Textpattern CMS.

• Download the latest release package from the Textpattern download page, select either the .zip or tar.gz package.
• Unzip (unpack) the Textpattern package into a folder on your local drive. You can now get familiar with the Textpattern folder/file structure before running through the setup processs.
• All folders and files in the unzipped package are organized under a directory named after the current release. You will install the files and folders contained within this directory; do not install the container directory itself!

Note: Textpattern is designed to work exactly as the folders and files are organized in the unzipped package, it is critical that you do not move, nor rename, any of the folders or files; doing so will cause Textpattern to not function.

• files – is empty by default, but will be utilized later in the course of building your site, particularly if/when you use the upload features in the Files Subtab.
• images – is empty by default, but will be utilized later in the course of building your site, particularly if/when you use the upload features in the Images Subtab.
• textpattern – is where the guts of Textpattern are stored. All the core scripting and functionality is kept in this folder. Again, do not move nor rename anything!

• .htaccess – is important for many reasons that are out of scope here, but not the least of which is handling URL formatting.
• HISTORY.txt – is a log of changes made to each Textpattern release.
• index.php – is effectively the stage of your site where all visitors will arrive and where everything takes place dynamically.
• README.txt – provides brief instruction on installing and upgrading.

For most people, Textpattern will be used to manage the entire website, whether it's a blog, business site, or photo gallery, etc. In this case Textpattern will be installed in the root level of your website; e.g., www.yoursite.com. (In case you're new to owning a Web site, this means in the public_html directory with most Web hosts.)

Others may wish to use Textpattern to manage a sub-section of an existing website, adding a blog, perhaps. In this case Textpattern would be installed to a subdirectory of that domain (e.g., www.yoursite.com/myblog). The /myblog subdirectory would need to be created prior to uploading the files.

To get files to your web server, you will need to use some form of File Transfer Protocol (FTP), so be sure to have one ready before proceeding. On some hosts, you may need to use a Secure File Transfer Protocol (SFTP) client. Now you should have an FTP client picked-out, installed, and linked properly with your Web host's servers.

Proceed as follows:

• Using your FTP or SFTP client, make a connection to your Web server, and navigate to the directory where you intend to install Textpattern. Then make a second FTP/SFTP connection to your local drive and navigate to the unzipped Textpattern package.
• Select all the files and folders within the install package. Upload these to your web server.

Note: FTP client - FileZilla, SFTP Client - WinSCP

Open a Web browser and open the /textpattern/ directory (e.g., www.yoursite.com/textpattern/).

Your browser should now be showing the the first screen of the installation setup, where you will add information about your MySQL database, and verify the site paths that it indicates; if not, double check the path you used to locate the /textpattern/setup/index.php file.

Before you can fill in the MySQL information, you will need to have established a few things on your host server. First, you will need to have given your database a name if it doesn't already have one. Next, you'll need to create a database login ID and password, and you'll need to have set the database login account with “write” privileges. Note also that when you fill in the Textpattern setup screen, you'll likely need to use your Web host user account ID as a prefix for the fields MySQL login and MySQL database. Here is a guide for how it should look:

MySQL login: yourhostID_databaseUserID
MySQL password: databasePassword
MySQL server: localhost (If “localhost” does not work, check with your host provider about what to use.)
MySQL database: yourhostID_datbaseName
Table prefix: prefix_ (e.g., txp_, txp2_, cats_, whatever_)

The Textpattern setup screen will indicate that you don't need to provide a table prefix if this will be your only intallation of Textpattern. It is advised that you create a prefix anyway. You might not need a second installation of Textpattern right now, but you might want to have one at a later point in time, and providing a prefix for this installation enables you to do that later. NB: make sure you use valid characters for MySQL for the prefix, only _ underscore $ dollar letters and numbers are allowed.

The site paths should already be filled in on your setup screen. You only need to verify that they are correct; but don't think too much about this, because if you added your Textpattern files as described previously, then these paths will be correct and you don't have to do anything.

The next stage of installation is to add your database and login details to the textpattern/config.php file. Textpattern makes this easy by taking the information you added in step 1 above, generates a snippet of code, and asks you to copy/paste the snippet into the textpattern/config.php file, replacing the contents of the file.

• Copy the code that Textpattern generated as indicated on the screen.

• Using your FTP client, navigate to textpattern/config.php.default in the unzipped files on your local drive and remove the .default extension from the file name. Open the file, paste the snippet of code into the file (replacing contents), save the file, and drag the file into the textpattern directory on your server. (If you want, you can delete the extra config.php.default file from your server, or move it to the unpacked folder on your local drive.)

• Go back to your browser window with the config setup screen, and click the “I did it” button for the config setup.

At this point, Textpattern is ready for you to add your account login information, and will then create the necessary tables in the MySQL database.

• Create a new user ID and password to administer your Textpattern site. (Note this is not the same ID and password used for your database, as discussed in step 1.)

• Click the “Next” button.

If all has gone well then you should see the confirmation screen. Now Textpattern has you delete the setup directory for security reasons. Do it.

• Use your FTP client, go to the /textpattern/setup directory and delete it from your server.

• Come back to the browser and click the “main interface” link at the top of the screen.

This will take you to the administration login screen for your new Textpattern site.

You should now have reached the administration login screen for your Textpattern installation. You should immediately make a bookmark for it in your browser for easy reference later.

To login to your admin interface, use the login information you created in step 3 above. If you want to avoid logging in each time you go to your admin pages, make sure the check box is selected (not advised if you share your computer with anyone).

When you first login, you will be taken to the Preferences Subtab panel in the administration area. There you will need to set your site preferences and default settings for how Textpattern should manage Comments by default. You should set your site preferences right away.

Note: After setting your preferences, you should visit the Diagnostics Subtab panel where you will be presented with some helpful diagnostics information to help troubleshoot any installation/setup problems.