Detailed Installation Instructions
From Textbook
This article is intended to help users with the installation process if the short instructions on the Textpattern download page don't work out for you.
Contents |
Acquisition and Unpacking
- Download the latest release package from the Textpattern download page. Select either .gzip or .zip as you prefer.
- Create a logically named folder (e.g., txp-unzipped) on your local drive, and unzip (unpack) the Textpattern package into the folder you create. You can now get familiar with the Textpattern folder/file structure before running through the setup processs.
Getting Familiar with the Folders and Files
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!
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.
The folders/files in the package are:
- textpattern (folder)
- All the core scripting and functionality is kept in this folder.
- images (folder)
- 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 admin-side's Images panel.
- files (folder)
- 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 admin-side's Files panel.
- rpc (folder)
- XML-RPC functionality is kept in this folder.
- sites (folder)
- Provides multi-site support; containing site template.
- index.php
- The default location of your site where web users will arrive, and where content publishing takes place dynamically.
- .htaccess
- Important for many reasons that are out of scope here, but not the least of which is handling URL formatting.
- css.php
- Handles the site's styles.
- README.txt
- Provides brief instruction on installing and upgrading.
- HISTORY.txt
- Changelog.
Where to Install on your Server?
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).
Add Files to your Server
To get files to your server, you will need to use some form of FTP/SFTP.
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 (except README.txt and HISTORY.txt) and upload these to your server.
Setup and Configuration
Step 1) Choose your language
- Open a Web browser and open the /textpattern/setup/ directory (e.g., www.yoursite.com/textpattern/setup/).
Your browser should now be showing "Welcome to Textpattern" and a dropdown list for choosing a language (if not, double check the path you used above). This language will be used for the installation screens and as the initial default for your Textpattern user interface. You can change languages later at any time. Choose a language and press Submit.
Step 2) Database Setup Screen
You should now see the first screen of the installation setup (Figure 1), where you will add information about your MySQL database, and verify the site paths that it indicates.
MySQL Database
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 installation 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.
Make sure you use valid characters for MySQL for the prefix, only underscore (_), dollar ($), letters and numbers are allowed.
Site Paths
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.
Step 3) Config File Setup Screen
The next stage of installation is to add your database and login details to the textpattern/config.php file as shown in Figure 2 below. 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-dist.php in the unzipped files on your local drive and remove -dist from the file name (so it reads config.php). Open the file, paste the snippet of code into the file (replacing contents), save the file, and transfer/drag the file into the textpattern directory on your server. (If you want, you can delete the extra config-dist.php 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.
Step 4) Creating Login Account
At this point, Textpattern is ready for you to add your account login information, as indicated in Figure 3 below, 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.
Step 5) Confirmation and Security Screen
If all has gone well then you should see the screen as shown in Figure 4. Now Textpattern has you delete the setup directory for security reasons. Do it now.
- Use your FTP client, go to the /textpattern/ directory and delete /setup/ 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.
Step 6) First Login Screen
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).
Finishing the Installation Process
Site Preferences
When you first login, you will be taken to the Language Preferences tab in the administration area. There you will need to set your site preferences and default settings for such things as how Textpattern should manage Comments by default. You usually set your site preferences right away.
Diagnostics
You should also visit the Diagnostics where you will be presented with some helpful diagnostics information to help troubleshoot any installation/setup problems. Clean URLs can cause a problem on some people's servers. Details about various diagnostic notices are provided in the Diagnostics documentation.
