Detail Installation Guide: Before You Start

By Melanie Cook
I've decided to write this, not to replace the GM Manual, which I find to be extremely useful, but to be used as an adjunct to the GM Manual for those who find installation a bit of a challenge.
Much of the information contained here is also in the GM Installation Instructions, which we are also going to use, in performing this installation. This is intended to be used with the guide, not instead of it!
My work has led me to teach myself to write keystroke by keystroke help for various tasks.
This is simply my effort to assist people with the installation of greymatter, hopefully answering such questions as What are my paths?, and where is Perl, and do I need to know what it is?.

I am also going to assume, in writing this, that you know you have access to a cgi-bin on your server. It doesn't matter if you don't know what it is, just that you have one. You also have to be able to upload and run your own cgi scripts. This also only covers installing greymatter on UNIX based servers.
The FTP software I personally use is WS_FTP. They have a light version available for free. There are lots of other FTP software packages out there. Which you choose is up to you. Any examples I'll give here though, will be from WS_FTP Pro, so any variations from that you'll have to work out for yourself.

I'm also assuming you've already downloaded greymatter. If not you can go here to get the latest version.

Right. With all of that done, we're about ready to start.
You may have already noticed some of the formatting I'll be using in this tutorial. I'll explain them below.

Links Links will be underlined.
Questions Questions, where I'm asking you to determine something, will have a grey background.
Help Help spots, where you can hold your mouse over the highlighted bordered text will provide popup information or explanations.
Code. Where I am telling you to type something into somewhere, I'll use this bordered, green text.
Greymatter boxes. When I want you to see what's in a Greymatter box already, or when I want to show you what's in my Greymatter box, I'll use the bordered mauve background.

We're ready to begin now, so we'll go to stage one.

Set up Greymatter Locally

Setup is probably a little misleading here. We're not actually going to "Setup" greymatter, rather we're going to duplicate your online setup.
If you haven't already done so, create a directory on your hard disk, for your weblog setup. Then create a cgi-bin directory inside the directory you just created, and unzip your Greymatter files into that directory. This is not a "working" cgi-bin. You are not going to be able to run greymatter from here, but it makes sense to store your files in a logical order.

Now create, inside your weblog directory, an archives directory. This is purely so that your local and your online setup is the same. This will simplify things later, and hopefully you'll get an understanding of how things work.

Now, I want you to find index.htm, manual.htm, gm-icon.gif and Install.html which should be in the cgi-bin directory and move them out of there and into the weblog directory.
You need to decide at this stage what extension you want your web pages to have. Are they going to be .htm? .html? .shtml? or .php?
Rename index.htm if you want it to be something other than that. (This is actually step three of the Installation instructions, which we will print next.)

Locate and open the file Install.html, and print it.

Don't worry about what the Requirements say, other than that you must be comfortable with editing HTML. I'll explain the rest to you as you need it. That's the whole purpose of this tutorial.
We're also not going to worry about the next step, Upgrading From Version 1.0 or 1.1, since I'm assuming if you need help with your installation you're not upgrading, but installing from scratch.
So. On to the next part. Installing For The First Time.

The next thing you need to do is locate perl on your webserver.
When you signed up for your domain hosting your host may have sent you a welcome email which included things like "where is perl" or "what and where is my mail program". You also need to know the path of your "home directory". If you have that, fine. If not, go to your domain hosts website, and look for their support or FAQ page, and try to find that information.
It may be on a page related to cgi-bin, or program locations. If you can't find it, and there's a search facility, try searching for perl. If that still doesn't help, send an email to your host asking for "the path to perl and the path to the mail program, and your home directory.".
These will commonly be /usr/bin/perl and /usr/bin/sendmail.

If perl on your server is in a different location, for example /usr/local/bin/perl you will need to edit the "gm.cgi", "gm-karma.cgi", "gm-comments.cgi" and "gm-upload.cgi".
The first line of these files should say "#!/usr/bin/perl". We need to change that to show where perl is on your server, so it says #!/usr/local/bin/perl for example, if that's what your perl path is. You can't use a normal windows editor for this. I use EditPad Lite which is free for non-commercial use. I used this before I got editpad - WinVi32, which is available free. It's a single executable file.
Make the changes to all four files, and save them.

Upload Greymatter

Open your FTP program. If this program uses profiles select the one for your webhost. If not, use your own method of configuring it to connect to your webhost.
There are two ways files can be uploaded using this type of software. ASCII or Binary. Your CGI files must be uploaded as ASCII files, or they won't work.
Upload all files ending in .cgi in ASCII format to your webservers cgi-bin directory. Also upload the 'libs' directory and all files within to the your cgi directory. In WS_FTP this is simply a matter of checking the radio button directly beneath the local and remote windows.
In WS_FTP Pro you are able to click the Options button, and then, on the extensions tab, select the file types you want to automatically upload as ASCII. I have mine set to do .cgi .pl .pm and .txt as ASCII. Everything else will, when you use the auto option, be uploaded as Binary.

NOTE Many people have issues with windows line endings (windows OS uses a different line ending character than other OS's). See the gm_manual file for more information.

Now you need to CHMOD "gm.cgi", "gm-karma.cgi", "gm-comments.cgi", "gm-upload.cgi" and all files withen the 'libs' directory (located withen the CGI directory) to 755. If your FTP program has a graphical interface for this, 755 means "rwx r-x r-x". (In WS_FTP right click the file, and then down towards the bottom of the popup menu you'll see chmod (UNIX)) CHMOD all of the other cgi files to 666, which means "-rw -rw -rw".

Upload the files from your local weblog directory, in Binary format, into your online weblog directory.
Now you need to CHMOD your index file to 666.
Make a directory online for your archives, with the same name as the one you made locally. CHMOD this to 777. (That's "rwx rwx rwx") (In WS_FTP you have a MkDir button which will enable you to create a directory on your webserver.) There is an image showing the directory levels here.

Now you're ready to login to Greymatter for the first time. In your web browser, go to the gm.cgi file you uploaded to your cgi-bin. Usually that would be at "http://www.yourdomain.com/cgi-bin/gm.cgi".
If everything did as it was supposed to, you'll be seeing the purple gm login screen.
If you're getting a 500 Server Error, or having other problems, upload your files again, making sure you use ASCII format. CHMOD them again, to make sure they're all CHMODed right. (It's quite simple to do them back to front and get the 4 that are meant to be 755 at 666 and the ones that should be at 666 at 755. I know.. I've done it myself!)
If it's still not working, go back and check the perl path. It must be correct in those four files, or gm.cgi isn't going to be able to find perl, and therefore won't run.
Still no luck, and I'd be checking with my host that my cgi-bin was properly configured. I've heard of hosts who, even though there is a cgi-bin in your directory don't actually configure it to allow files to run until you ask them to. Find out if there are any restrictions on running your own scripts.
Failing that, you've got me stumped. If all of that is set correctly I can think of no reason why greymatter wouldn't be working so far.
There are online Greymatter Forums where you can go to ask for help.

We're continuing now, from the login screen. The default login is Alice, and the password is wonderland.

You're in! You at least got it installed! Congratulations!

Configuring Greymatter

Now you have to configure it. This means we're going to tell it how and where you want everything.
Greymatter assumes that all files for your weblog or journal are going to be in the same directory. We're not going to do that. We're going to have our cgi files in the cgi-bin, and the log and entry files in their own directories. This is why the assumptions greymatter makes below don't suit this installation. To do this click on the Configuration button on the welcome screen.
For the purposes of this tutorial you need to know that on my server

• My perl path is /usr/bin/perl, so I didn't have to edit my cgi files.
• My mail path is /usr/sbin/sendmail.
• My domain is called wiccked.
• My home directory is /home/wiccked/public_html.

Greymatter tells me my

• Local Log Path is: /home/theonion/public_html/wiccked/cgi-bin
• Local Entries/Archives path is: /home/theonion/public_html/wiccked/cgi-bin/archives
• Local CGI Path is: /home/theonion/public_html/wiccked/cgi-bin
• Website Log Path is: http://wiccked.com/cgi-bin
• Website Entries path is: http://wiccked.com/cgi-bin/archives
• Website CGI Path is: http://wiccked.com/cgi-bin

Now, I know, that these are not all correct. I'll copy the correct ones below, and tell you beside them why what greymatter assumed is wrong.

• Local Log Path is: /home/wiccked/public_html - greymatter had assumed the main index page was going to be in the same directory as the cgi-bin.
• Local Entries/Archives path is: /home/theonion/public_html/wiccked/archives - again, gm had assumed the archives directory was to be in the cgi-bin.
• Local CGI Path is: /home/theonion/public_html/wiccked/cgi-bin - This one gm usually gets right.
• Website Log Path is: http://wiccked.com - As in the local log path, gm assumes the main index page is going to be in the cgi-bin.
• Website Entries path is: http://wiccked.com/archives - The same again. The archives aren't in the cgi-bin.
• Website CGI Path is: http://wiccked.com/cgi-bin - And it got this one right too.

I'm not sure why greymatter assumes that the logs and archives are going to be inside the cgi-bin, since most webhosts wouldn't like that at all. But it does, so we fix it. But this seems to be one of the part of configuring greymatter that people find most confusing.
But you've got this far. The hard bit is almost done.

File Names and Archives

Greymatter wants to know now

• Index filename:
  The filename of your log/journal's main index. If you enable "Keep archive master index", Greymatter will create that file in the archives directory with the same filename.
  index.php or whatever you decided to call it. (make sure it's the same as the file you uploaded!)
• .suffix to entry files:
  If you have "Generate pages for individual entries" enabled, this is the suffix those pages will have.
  .php (or whatever you decided to use)
• .suffix to log archives:
  If you have "Keep monthly/weekly log archives" enabled, this is the suffix those log archive files will have.
  .php (again, the extension you decided to use.)
• Days to keep on main index:
  The number of days' worth of entries Greymatter will list on your main index before scrolling them off.
  When you start setting up your templates, you'll probably include either an extract or complete entries, for however many days you set this to. Mine is set to 7    7   
• Generate pages for individual entries?
  Specifies whether you want individual entries to have their own pages. Comments are disabled if this is turned off.
  Radio button selection of "Yes" or "No "
• Keep archive master index? If enabled, Greymatter will keep an index (with the same filename as above) in your entries/archives directory, intended to be an overview of all your archives.
  Radio button selection of "Yes" or "No " (An example of what you get for Yes is here)
• Keep monthly/weekly log archives?
  If enabled, Greymatter will keep archive files of your log in monthly or weekly instalments in your entries/archives directory.
  Radio button selection of "Yes" or "No " (An example of what you get for yes is here)
• Keep main index and archive log indexes concurrent with each other?
  If enabled, both new and archived entries will be listed in the monthly/weekly archives; if disabled, Greymatter won't list entries there until they've scrolled off the main index. For simplicity's sake, it's a good idea leave this on.
  Radio button selection of "Yes" or "No "
• Archive by month or week?
  If "Keep monthly/weekly log archives" is enabled, this specifies whether the log archives will be generated by the month or by the week.
  Radio button selection of "Monthly" or "Weekly"

E-Mail, Karma Voting, and Comments

• E-Mail Options
  Options relating to e-mail setup and notification. If you don't plan to have Greymatter send you e-mails, you can safely ignore the "E-Mail Program Location" and "E-Mail(s) to send notices to" fields.
• E-Mail Program Location:
  The pointer to the mail program (usually Sendmail) on your account.
  /usr/sbin/sendmail (or whatever is appropriate to your own server!)
• E-Mail(s) to send notices to:
  The e-mail addresses you want all notifications (if any) to be sent to. Separate multiple e-mail addresses with semicolons.
  youremailaddress@yourdomain.com
• Send e-mail notifications for:
  Indicates whether you want Greymatter to send e-mails notifying you of new karma votes, new comment postings, both karma and comments, or to disable e-mail notification altogether.
  Radio Button selection of "New karma votes" "New comments" "Both" "Neither"



• Karma & Comments Options
  Options relating to karma voting and comment posting. Obviously, certain options can be ignored if you have their respective functions disabled (for example, if you disable comments or have "Generate pages for individual entries" turned off, none of the options relating to comments will have any effect).
• Allow karma voting and/or comment posting?
  Specifies whether you want to permit voting on karma, posting comments, both, or neither, on your site. You can leave them enabled and still turn karma or comments on or off for individual entries; to disable either or both will override that for ALL entries.
  Radio Button selection of "Karma only" "Comments only" "Both" "Neither"
• Order of comments on entry pages:
  The order in which you want comments displayed. If "ascending", they'll be listed from newest to oldest, with the newest comment at the top; if "descending", from first to last, with the first comment at the top.
  Radio Button selection of "Ascending" "Descending"
• Can post comments and vote on karma in archives?
  If enabled, visitors can cast karma votes or post comments (if applicable) on entries no longer listed on the main index. Enabling this may slow down your site over time.
  If you answer Yes to this question people will NOT be able to cast karma votes or post comments once an entry has gone from your main index page. If you have only one entry on your main index page that is all that will allow comments to be posted!
  Radio Button selection of "Yes" "No"
• Karma voting on by default?
  Specifies whether "Allow karma voting on this entry" is preselected to "Yes" or "No" by default on the "Add a new entry" screen.
  Radio Button selection of "Yes" "No"
• Comment posting on by default?
  Specifies whether "Allow comments to be posted to this entry" is preselected to "Yes" or "No" by default on the "Add a new entry" screen.
  Radio Button selection of "Yes" "No"
• HTML allowed in comments?
  Indicates whether you want to allow visitors to include HTML codes in their comments, or to have Greymatter strip them out. You can also specify whether only the codes for links, bold and italics can be included, or just the codes for links.
  Radio button selection of "All HTML allowed" "No HTML allowed" "Linking, Bold & Italic code only" "Linking code only"
• Auto-link URLs in comments?
  If enabled, Greymatter will automatically link to any website or e-mail addresses that users post in their comments (unless you've enabled linking above and they've already linked the website/e-mail address themselves).
  Radio Button selection of "Yes" "No"
• Strip new lines from comments?
  If enabled, all line and paragraph breaks are stripped when displaying visitors' comments, turning them into unbroken blocks of text; if disabled, Greymatter preserves the visitors' original formatting.
  Radio Button selection of "Yes" "No"
• Allow multiple karma votes from same IP?
  If enabled, the same visitor could cast multiple karma votes on the same entry; if disabled, only one vote per visitor is allowed.
  Radio Button selection of "Yes" "No"
• Mention it in the control panel log when comments and karma votes are added?
  Enable this if you want Greymatter to mention all new comments and karma votes in the control panel log.
  Radio Button selection of "Yes" "No"



• Date & Time Options
  Miscellaneous options regarding to dates & times. Use the wide variety date and time variables in your templates to fine-tune how you want the date and time to appear on your site.
• Server Offset Time:
  As of this moment, Greymatter reads your time as 6:13 AM. If this is incorrect, specify the number of hours to add or subtract from this time (to subtract, make it a negative number, with a minus in front of it).
  If you know where your server is located, you need to take the day into account too. If Greymatter is telling you the server time is 6:13 AM, and you know that because of your geographical location and that of your server that this is on a different day your time difference needs to reflect this. My time is 9:13 PM, so I need to set the time offset as +15, since there are 15 hours difference between my server time, and my local time. This can be quite complicated to work out, and it may take a couple ot tries to ensure you end up with the correct time and date on your entries. Test entries are good to use for this.
  15
• Your Time Zone:
  The time zone you live in. This is what will appear wherever you use the {{timezone}} variable in your templates.
  (Enter your own time zone. Remember to allow for daylight savings here. If your server changes time for daylight savings this may need to be reset at the start and end of daylight savings time.)
  AEST



• File Uploading Options
  Options relating to uploading files from within Greymatter.
• Allowed File Types:
  If you only wish to allow certain types of files to be uploaded, enter their file suffixes here. Separate allowed file types by semicolons (for example, "jpg;gif;zip"). Leave this blank to allow any type of file to be uploaded.
           
• Maximum Filesize Allowed:
  If you don't wish to allow files larger than a certain size to be uploaded, specify that limit here (in KB/kilobytes). Leave this on "0" to allow files of any size to be uploaded.
           
  KB


• Censoring Options
  Words or phrases you want to censor on your site (if any), and where to censor them.
  Censored terms will be turned into "*" asterisks.
  
• Enable censoring?
  Specifies whether you want any words or phrases in your censor list to appear censored for entries, comments, or both. Leave it on "Neither" to disable censorship.
  Radio button selection of "Entries only" "Comments only" "Both" "Neither"
• Censor List
  Enter any words or phrases you want to censor, separated by lines (press return after each word/phrase). Use [brackets] around words/phrases to censor the term only if it's not part of another word/phrase; for example, censoring the word hell would render hell as **** and shell as s****, but censoring [hell] would only turn hell by itself into asterisks, and leave the word shell alone.
           



• Connect Other Files (Advanced Users Only) * I will add further explanations to this at a later date.
  If you wish, you can connect other files on your account to Greymatter, and have them treated as if they were one of Greymatter's regular index files; for example, using {{header}} or {{footer}} in another file to insert your Greymatter header or footer into that file. (You'll need to edit & upload these files to your account outside Greymatter.) This is only recommended for advanced users that are already comfortable using Greymatter.
• Filename List
  To connect a file to Greymatter, CHMOD it to 666 making sure it contains whatever Greymatter variables you wish and enter its filename on the right;
  place each filename on separate lines. If the file isn't in the same directory as gm.cgi, then use virtual paths relative to where it's running from. For example, if you want to connect "test.htm" and it's in the directory above gm.cgi, you'd use ../test.htm; or, if you run gm.cgi from /here/cgi-bin and test.htm was in /there/log, you'd use ../../there/log ("../" means to go up one directory). Greymatter will automatically create a "pattern" file in your entries directory for each filename, and whenever you reupload a changed file, Greymatter will automatically update its stored pattern for that file.
           
• Update them when adding entries?
  If "Yes", then Greymatter will automatically update any of the connected files above when new entries are added; if not, they'll only be updated whenever you rebuild them (either specifically, or by rebuilding everything).
  Radio Button selection of "Yes" "No"



• Miscellaneous Options
• Enable cookies?
  By default, Greymatter keeps a cookie on your browser that remembers your name and password, so you don't have to type them in each time you log on. To disable and delete Greymatter's cookies, select "No" and check the checkbox.
  If you use a shared computer, and do not want others to have access to Greymatter you should set this to No, and tick the box.
  Radio Button selection of "Yes" "No", and "Delete cookies set by Greymatter?" tickbox.
• Keep control panel log?
  Specifies whether you want Greymatter to keep its internal log of all activity; disable this if you want to shut it off.
  Radio Button selection of "Yes" "No"
• Allow "easy formatting"?
  With "easy formatting", bold text, italics & underlining can be done easily by bracketing text with two **asterisks**, \\backslashes\\ or __underlines__ respectively. You can specify whether this is enabled in entries, comments, or both; if disabled, the characters won't be converted.
  Radio Button selection of "Entries only" "Comments only" "Both" "Neither"
• Default entry list view:
  This specifies which view will be the default when you go to the Edit An Entry selection menu.
  Under normal use Current entries is probably fine. If you need to edit a lot of entries outside that range, temporarily change this option
  Selection list choice of "Current entries (7 days)" "All entries by you" "All extended entries" "All open entries" "All closed entries" "All entries"
• Order of list links:
  The order in which you want links to be displayed in log list variables, check the manual for more information on those. If "ascending", the links will be listed from newest to oldest, with the newest entry at the top; if "descending", from first to last, with the first entry at the top.
  Radio Button selection of "Ascending" "Descending"
• Log entry list variable number:
  The number of entries to link to, starting from the most recent, whenever the "number" variant of the log entrylist variables (for example, if this is set to 5, using {{logmoreentrylist number}} would generate a list of links to the five most recent extended entries). Check the manual for more information on those variables.
           
• Link to entries in {{logentrylist comments}} only if comments are active?
  If you use {{logentrylist comments}} and its related variables (see the manual for more information), this specifies whether to list only entries to which comments can still be posted.
  Radio Button selection of "Yes" "No"
• Entries to link to in {{calendar}}:
  Whenever you use {{calendar}} or {{calendarweek}} to generate tables linking to your entries, this specifies whether you want to link to the most recent entry for that day, or to link only to extended entries. (It won't generate links at all if "Generate pages for individual entries" is turned off.)
  Radio Button selection of "Always link to entry for that calendar day" "Link only to extended entries"
  
• "Automatically rebuild" selected by default?
  Selects whether the option to automatically rebuild files after saving changes to templates or entries is prechecked by default. (Authors without access to rebuilding files won't see this option.)
  Radio Button selection of "Yes" "No"

Now you've configured Greymatter you need to run diagnostics & repair to ensure that all of the paths and permissions are correct. Click on the Diagnostics & Repair button.
Once you click the next button, Greymatter will check that it is able to run correctly, and that it is able to write to the directories required to add your entries etc. Click the Peform Diagnostics & Repair button.

Greymatter will hopefully report that Diagnostics & Repair Complete
All operations were completed successfully. Greymatter successfully checked and/or performed the following:

• All config files are readable/writeable and are CHMODed correctly
• The local CGI path is correctly configured and all essential files are there
• The entries/archives path is readable/writeable and is CHMODed correctly
• The main index file is readable/writeable and is CHMODed correctly

If any errors are reported, read them carefully. They should provide you with enough information to correct them. For example, if you are told that Greymatter can't write to /home/theonion/public_html/wiccked/cgi-bin/archives/ you have probably got the local archives path set incorrectly. Change it to leave "cgi-bin" out of the path, then re-run the diagnostics program.
If the path is correct but Greymatter is telling you it can't write to the directory CHMOD it again, ensuring permissions are set as laid out in the Upload Greymatter section of this tutorial.
Once all is correct you can Return to Main Menu

Your Greymatter installation still only has Alice as the default author, so we select Edit Authors to add you, and to delete Alice. Add yourself before you delete Alice. Don't delete Alice until you've successfully logged in as yourself.
Fill in the "Register a New Author" box.
Enter the appropriate details into the
Name:              Password:              Email:              Homepage:          boxes.
Set the "Default Author Access" for this Author.
Radio button selection of "All access" "No access" "Post & edit their own entries only" and then click the Create Author button.
When you have added all the authors you want to add click the Return to Main Menu button.
Click the Re-Login button.
Enter your own author details, and login.
You can now go back into Edit Authors and delete Alice, by selecting Alices radio button, and clicking the Delete Selected Author button.

You're ready to start setting up your templates now. The simplest place to start is by adding an entry. Don't write your life story or anything, just make it a very brief first entry. This will enable you to see what formatting is there.
From here, if you're comfortable continuing with the templates by yourself, have fun. Enjoy Greymatter, and please let me know if you found this useful, or if you have any suggestions for something you'd like to see added here.