How to Install GreyMatter 1.3

What is GreyMatter?

GreyMatter is a web log or journal program, otherwise known as a blog. GreyMatter can be used to enter your thoughts, news, updates or whatever else you would like on your site using an easy interface. GreyMatter also automatically archives your entries so your visitors can view what you've posted in the past. In addition, GreyMatter has the option of letting your visitors leave a comment or a vote for each of your entries. GreyMatter is versatile and easy to set up and use. You can customize GreyMatter's templates to match your site design as well.

Please read the instructions carefully. Most problems with installation can be avoided by following each step precisely.

Requirements:

To use GreyMatter, you need to be sure your CGI account is set up. Please see How To Request A CGI Account for more information. You will also need to download a copy of GreyMatter. The version used in this tutorial was GreyMatter 1.3.

Restrictions:

Remember that only your main account can access CGI scripts on your server. Any hosting or extra FTP accounts that access these scripts may cause your account to be deactivated and you'll have to contact support.

For GreyMatter to work correctly, please do not put it or it's directories inside your cgi-bin directory. If you do, the archive directory may not be accessable to GreyMatter. It's best to use a separate directory and leave the cgi-bin directory for your smaller scripts.

Installation:

1. After downloading GreyMatter, extract the files to a directory on your hard drive.

2. Be sure the following GreyMatter files have the first line set to:
   
   #!/usr/bin/perl
   
   Usually this is default in GreyMatter, but listed here in case it should change. The files to check are gm.cgi, gm-karma.cgi, gm-comments.cgi, and gm-upload.cgi.

3. Start up your FTP program and log into your CGI server (which should be something like cgi.yourdomain.com where yourdomain.com represents your domain name).
   
   Create a new directory called gm (or name it anything else you'd like).
   
   Upload all the files and directories to the new directory. Be sure that all files (except the image files) are uploaded in ASCII mode. Please see your FTP program's documentation to learn how to do this. The image files must be uploaded in Binary mode.

4. Use your FTP program to change file permissions. Usually you can do this by right clicking on a file and finding either "Attributes", "Permissions", or "CHMOD" in the menu. The following file permissions should be changed as follows:

   Files	Permission (CHMOD)
   gm.cgi, gm-karma.cgi, gm-comments.cgi, gm-upload.cgi	755
   All other .cgi files except gm-library.cgi	666
   index.html	666

   Tip: Some FTP programs let you select multiple files by holding down the CTRL key and clicking on additional files. Then right click on the selected files to select the menu item to make the change.

5. Create a new directory inside this directory and name it archives. Change this directory's file permission to "777". Note that you can name this directory anything you like, just remember this when you go to configure GreyMatter. By default, GreyMatter puts it's automatically archived entries in the archives directory.

6. Log off your CGI server. You are ready to proceed with configuration.

Configuration:

1. Point your web browser to gm.cgi in your new GreyMatter directory. This could be something like the following:
   
   http://cgi.yourdomain.com/gm/gm.cgi
   
   Where yourdomain.com represents your actual domain name and gm is represents the directory you uploaded your GreyMatter files to.

2. Log in using the username Alice and the password wonderland. This is the default administration username and password which you will change later.

3. Click on the Configuration button at the top left.

4. Enter in the following information. Note that gm represents your GreyMatter directory and yourdomain.com represents your domain name. Replace them accordingly if necessary. Normally, GreyMatter should automatically detect and fill these in for you. Just go over them and be sure they were correctly entered.
   
   NOTE: The emoticons path isn't normally filled in correctly so you may have to put in the full path. Be sure the full path is used as shown below and not just the directory name.

   Local Log Path:	/var/www/sites/yourdomain.com/gm
   Local Entries/Archives Path:	/var/www/sites/yourdomain.com/gm/archives
   Local CGI Path:	/var/www/sites/yourdomain.com/gm
   Website Log Path:	http://cgi.yourdomain.com/gm/
   Website Entries Path:	http://cgi.yourdomain.com/gm/archives
   Website CGI Path:	http://cgi.yourdomain.com/gm/
   Emoticons Path:	/var/www/sites/yourdomain.com/gm/emoticons

   The other information you may leave as default if you wish. Scroll down to E-Mail Options and be sure the E-Mail Program Location is set to /usr/sbin/sendmail and fill in your email address and options.
   
   Decide whether you want to use smiley faces (emoticons) or not in your posts and/or comments.
   
   Read the descriptions for each category and decide how you would like to set up each feature. Each feature's description is pretty much self-explanatory.
   
   Click on the Save Configuration button when done.

5. Click on Rebuild Files. There will be a message at the top that there are no entries yet. Ignore this message for now.

6. Click on the Configuration button and scroll down to the bottom. Click on the Diagnostics & Repair button. Next click Perform Diagnostics & Repair. When done click on Return To Main Menu.

7. Click on the Edit Authors button. Enter your username, email address, a password and your web site URL. Be sure that All Access is the Default Author Access. Click on Create New Author.
   
   Click on the radio button next to the Alice author and click Delete Selected Author. Finally log in with your new Username and password. Click on Create New Author.

8. Click on the Add New Entry button and add your first entry. This can be your first journal entry, an update or a welcome message.

9. Point your browser to your web log at:
   
   http://cgi.yourdomain.com/gm/index.html
   
   Where yourdomain.com represents your actual domain name. This link is the actual link you give to your visitors to view your blog.

NOTE: Anytime you make changes to your configuration, always Rebuild your files. It's recommended that you Rebuild Everything unless you know exactly what items need rebuilding.

Customizing Greymatter to Match Your Site:

GreyMatter lets you customize it to match the look of your site. There are far too many features to cover in this tutorial. However, here we will cover the basics. Explore the other templates and you can figure out how they are put together. Just be sure not to edit out items in double-braces {{ }} unless you are very sure of what you are doing.

Tip: When making changes to the templates, cut and copy the text into an ASCII text editor and save it to a file on your local hard drive as a backup, just in case you make a mistake and need to restore the original template.

Log into GreyMatter by going to http://cgi.yourdomain.com/gm/gm.cgi and entering your username and password. Click on Edit Templates. Click on Edit Header, Footer & Sidebar Templates. Here you can edit the HTML code to display the way you'd like. It is recommended you know a bit about HTML and Cascading Style Sheets (CSS).

Header Template:

Add the title in the <title></title> tags, and the colors for your site in the style area. Alternatively, you can delete the style area and use a link to your own stylesheet. Just be sure that the same items in the style area in GreyMatter are included in your own style sheet. To link to your own style sheet, put this after the title tags and be sure the entire text is all on one line:

<link REL="stylesheet" href="http://yourdomain.com/template.css" TYPE="text/css">

Where yourdomain.com/template.css represents the full URL to your own stylesheet file.

Footer Template:

This you should not edit unless you've removed tags from the other templates on this page.

Sidebar Template:

Here is where you can add links to your site, link buttons, or whatever else you wish. Edit this area to your liking. Be careful not to remove any items in double-brakets {{ }}.

You can add other custom templates as well, and use them in the other templates. Just refer to them as {{customone}}, {{customtwo}}, etc. in your other templates to insert those codes into any other templates you edit in GreyMatter.

Saving Your Template Changes

After saving the changes, always Rebuild Files and Rebuild Everything so that all pages will take on the new template changes.

Changing the GreyMatter Icon:

You can change the icon for GreyMatter displayed on the page. Just create a new gm-icon.gif and upload it to your GreyMatter directory. Be sure you upload it in Binary mode. The GIF should be 88 x 31 in size.

More Information:

For more information on installing and customizing GreyMatter, please read the install.html and manual.html files that come with GreyMatter.

Troubleshooting:

Nothing works. I get a 500 Internal Server Error from my web browser.

• Be sure that your file permissions are set right. See step # 4 in the Installation section above for more information.

• Be sure you have uploaded all the necessary files to your CGI server and created the archive directory.

• Be sure that you set the path to the Perl Interpeter correctly. See step # 2 in the Installation section above for more information.

I can't see emoticons or graphical smileys.

• In the GreyMatter Configuration, be sure that you have HTML allowed in ] comments? set to All HTML allowed.

• Be sure you have emoticons turned on in the GreyMatter Configuration.

• Be sure that the path to the emoticons is set correctly. See step # 4 in the Configuration section above for more information. Do not use a virtual or relative path such as ./ or ./emoticons to point to your smilies directory as that may not work when people go to post comments. The path must be a direct local path to the directory as shown in step # 4 in the above Configuration section.

• Be sure that you have uploaded all the smiley faces in the emoticons directory using he Binary mode in your FTP program. You might also try setting the smiley images permissions to "666".

• Your web browser may have JavaScript turned off, or not support the JavaScript code to display the smiley faces. You should still see text where the smiles are. Turn on JavaScript in your browser. If it already is on and no smilies are showing up, then try another web browser. It has been tested that Firefox 1.0 will not show smilies when a user posts a comment to your post, but Internet Explorer 6 will show them fine.

• Do not drag and drop smilies into your posts. This may instead produce a link to the smiley graphic instead of displaying the actual smile face. Do not use the smilies in any other area of your post except the main and extended areas.

My Archives are not showing up or working.

• Be sure that your directory and file permissions are set correctly. Please see Step # 4 in the Installation section above for more information.

• Do not use a virtual or relative pathname in the Configuration even though GreyMatter mentions you can use ./ or . or even ../ as part or all of your path name. Use the actuall direct local path or URL as shown in Step # 4 of the Configuration section.

Support:

If you have any problems or questions about GreyMatter, please contact the author at this site: http://www.noahgrey.com/greysoft/

Active Web Hosting may not be able to provide support for this program or it's installation.

Alternative Software:

Below you'll find a list of alternative software that you may also want to try. Click on the program name to go to the author's site. Click on the 'Tutorial' link to view our installation tutorial.

• bBlog
• WordPress 1.5
• b2Evolution