GreyMatter
Weblog/Journal Software · Version 1.21d · Installation Instructions
Copyright ©2003 Noah Grey and Richard Foshee · All Rights Reserved
Requirements
GreyMatter requires the ability to run Perl software on your account on your Web server and an FTP client (such as CuteFTP) to upload the files to your account and CHMOD them on the server. Also, you should be modestly comfortable with editing HTML to customize the templates, and thus make your Weblog, journal, or photolog truly your own.
Upgrading From a Previous Version of GreyMatter
Users of a previous version of GreyMatter should download the 1.21d zip/tar file the downloads page and then upload the new files to your server.
Before You Start
During the process of installing GreyMatter, you will need to know some things about your account on your Web server and how you want your site to work. It would be helpful if you wrote them down or had them stored electronically, so you could have them as a reference. Yes, it's time to take some notes. :)
- Where is Perl?
The location of Perl is vitally important to running GreyMatter. Your Web host can tell you where Perl is located, or you can find out for yourself if you have access via telnet or SSH to your server. If you have such access, type 'whereis perl' at the prompt, and make note of that location. It will be something like '/usr/bin/perl', '/usr/local/bin/perl', or '/usr/bin/perl5' on a Unix server. On a Windows server, it may be 'C:/perl/bin/perl.exe'.
Once you know the location of Perl, make a note of it, and go on to the next step. - What will your site structure be?
It seems silly to think about this so early, but setting the site structure is like building the foundation for a house. That's why we'll lay a good foundation now.
First, it will be important to know how you want your log to appear. Some people like to have their GreyMatter-powered log appear on the main page of their site; when that is the case, bringing up http://www.mysite.com/ will show the log. Others like to have their log in another place, in what is called a subdirectory. In that case, it's usually something like http://www.mysite.com/log/, where /log/ is the location of the log.
So, take some time to think about it. GreyMatter needs to know two things to properly present your log: where your main page for your log will be, and where you want your archives to be. If you wanted your main log to be at http://www.mysite.com/weblog/, and the archives folder for that to be called "blatherings", your archives will be stored at http://www.mysite.com/weblog/blatherings/. - Where are your CGI files kept on the server?
When you upload and install GreyMatter, it will take a good stab how your Web server is set up. It will always find the directory where CGI files should be kept, assuming that you upload it to the right place.
To make sure you do it right, start your FTP program and just look at your account's main folder. What is that folder called? [Write that down; if you can't see, try to go "up" a folder and see if you can see that.] Do you see a folder named /cgi-bin/? If so, find that, and make a note of where it is in relation to the main folder of your site. That will help you later on in the installation process.
Once you've made these notes, you're ready to roll.
Installing For The First Time
- Make sure you meet all the requirements, as specified above.
- Separately, open the files "gm.cgi", "gm-karma.cgi","gm-comments.cgi", and "gm-upload.cgi", and look at the very first line, which should say "#!/usr/bin/perl". Make sure that the Perl pointer here is correct; refer to your notes that you made. If, for example, your Perl directory is '/usr/local/bin/perl', change the first line in each of the four files to reflect that. You must maintain the #! [the shebang, if you're wondering what to call it] before the directory, or it just won't work. This is the only time you'll ever need to touch the GreyMatter program code.
- Refer to your notes above about site structure. If you want your main index file to be named something other than "index.htm", then rename the included index.htm file accordingly. For clarity's sake, we'll assume "index.htm" with the rest of the instructions.
- Open your FTP program. Important note: All files except "gm-icon.gif" must be uploaded in ASCII mode; check your FTP program to find out how to make sure that all CGI files are uploaded as ASCII and not binary files.
- Upload all the GreyMatter CGI files (they all begin with "gm" and end with ".cgi") to the CGI files directory you found above in your notes. All these files must be in the same directory on your account.
- CHMOD the files "gm.cgi", "gm-karma.cgi", "gm-comments.cgi", and "gm-upload.cgi" to 755, and CHMOD all the other .cgi files to 666.
- Upload index.htm (or whatever you've renamed it to) and gm-icon.gif to the place where you want your log to be. Refer to your notes above for that process.
- CHMOD the index.htm file (or whatever you've renamed it to) to 666.
- Create the directory where all your log entries and archives will be stored. Refer to your notes above when creating this directory. By default, GreyMatter will assume you name this directory "archives", but you can name it whatever you wish.
- CHMOD your entries/archives directory to 777.
- Open your Web browser and run gm.cgi on your site (for example, if you run www.mysite.com and you uploaded the GreyMatter files to the /cgi-bin/ subdirectory, then you'd type http://www.mysite.com/cgi-bin/gm.cgi in your browser). If all of the above went okay, then you should now see the GreyMatter logon prompt. (If you're getting a 500 Server Error or having other problems attempting to run gm.cgi, go back and make sure that everything is uploaded and chmoded correctly; read the "Troubleshooting" section in the manual for more information.)
- Log on with the author name "Alice", and the password "wonderland".
Configuring Your Paths
Welcome to GreyMatter! The next step is to configure your paths. Refer to your notes above on your site structure.
We'll use the following example site structure to explain the paths setup; this is where a sizable group of new GreyMatter users have gotten confused before, so we'll work with this example and use it to explain all six paths.
Our example comes from the site structure of Geof Morris, one of the authors of this set of installation instructions. [Though it's about to be re-designed, it will still be clear for you.]
Geof's site is http://www.ijsm.org/, and he hosts a log on the front page. His entries and archives folder is /journal/, so it's found at http://www.ijsm.org/journal/. His server requires CGI files to be in the /cgi-bin/ directory, so his GreyMatter installation is found at http://www.ijsm.org/cgi-bin/gm.cgi .
Now, the first time you look at your paths, they'll be wrong. That's okay! For an example, here's what Geof saw the first time he installed GreyMatter:
Local Log: /home/ijsm/public_html/cgi-bin
Local Entries/Archives: /home/ijsm/public_html/cgi-bin/archives/
Local CGI: /home/ijsm/public_html/cgi-bin
Website Log: http://www.ijsm.org/cgi-bin
Website Entries/Archives: http://www.ijsm.org/cgi-bin/archives/
Website CGI: http://www.ijsm.org/cgi-bin
This wasn't what Geof wanted, so he had to start changing things.
First off, he wanted http://www.ijsm.org/ to be where his log appeared. So, he changed the Log paths to:
Local Log: /home/ijsm/public_html
Website Log: http://www.ijsm.org/
Next, he'd created /journal/ in the main directory of his site, and that's where he wanted his archives and entries to be. So the Entries/Archives paths were going to have to change. Here's what they became:
Local Entries/Archives: /home/ijsm/public_html/journal/
Website Entries/Archives: http://www.ijsm.org/journal/
What about the CGI files? Well, that's what GreyMatter gets correct every time. There's no need to change the two CGI paths, unless you want GreyMatter in a subdirectory of your /cgi-bin/ directory.
Diagnostics and Repair, Author Configuration
Return to Configuration and click "Diagnostics & Repair". This routine checks to see that all your files and paths are working correctly. If you aren't able to run it successfully, your paths are probably incorrect; check the Troubleshooting section of the manual. Once you've run it successfully, you'll be able to post your first entry.
Click "Edit Authors", create a new account for yourself with the name and password you'd like to use, and delete Alice. (You could keep Alice around, but for obvious security reasons, it's not recommended.) Since you're still logged on as Alice, you'll need to re-enter under the new name and password.
All done! You should now be able to post entries and get your Weblog, journal, or photolog going. (It's a good idea to set up a private test log first, and try creating and editing a few test entries, simply so you can get the hang of GreyMatter before doing it "for real".)
GreyMatter uses an extensive template system to allow you total control over every aspect of your Weblog and all the pages & elements it'll comprise. The default templates included with GreyMatter are quite plain-jane, but they should be enough to provide a starting point and, hopefully, to give you a basic idea of GreyMatter's template & variable usage. Change the templates as much as you like (and just reupload the gm-templates.cgi file if you mess things up too much and want to start over) to suit your own design and style; refer to the GreyMatter manual for full information about all the template variables.
And that's that! Hopefully by now you're up and running in some form--after you add your first entry, open another window in your browser and load up your log's intended location. You can alter your templates anytime to change any aspect of your log's design and layout (be sure to "Rebuild Files" after changing the templates for GreyMatter to automatically update your site accordingly). Enjoy doing your log, and thanks for using GreyMatter. =)
Copyright ©2000-2001 Noah Grey. All rights reserved.