moved qdb here because matt is lazy
[public/www-new.git] / pub / qdb / install.txt
1 ###############################################################################\r
2 # Chirpy! 0.3, a quote management system                                      #\r
3 # Copyright (C) 2005-2007 Tim De Pauw <ceetee@users.sourceforge.net>          #\r
4 ###############################################################################\r
5 # This program is free software; you can redistribute it and/or modify it     #\r
6 # under the terms of the GNU General Public License as published by the Free  #\r
7 # Software Foundation; either version 2 of the License, or (at your option)   #\r
8 # any later version.                                                          #\r
9 #                                                                             #\r
10 # This program is distributed in the hope that it will be useful, but WITHOUT #\r
11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #\r
12 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for   #\r
13 # more details.                                                               #\r
14 #                                                                             #\r
15 # You should have received a copy of the GNU General Public License along     #\r
16 # with this program; if not, write to the Free Software Foundation, Inc., 51  #\r
17 # Franklin St, Fifth Floor, Boston, MA  02110-1301  USA                       #\r
18 ###############################################################################\r
19 \r
20 ###############################################################################\r
21 # INSTALLATION INSTRUCTIONS                                                   #\r
22 ###############################################################################\r
23 \r
24 \r
25 CONTENTS\r
26 ========\r
27 \r
28 1. INTRODUCTION\r
29 \r
30 2. REQUIREMENTS\r
31 \r
32 3. INSTALLATION\r
33 3.1. Copy files\r
34 3.2. Configure\r
35 3.2.1. The [general] Section\r
36 3.2.2. The [data] Section\r
37 3.2.3. The [ui] Section\r
38 3.3. Setup\r
39 3.4. Import\r
40 \r
41 4. UPGRADING\r
42 \r
43 5. RUN CHIRPY!\r
44 \r
45 6. NEXT STEPS\r
46 6.1. Your Own Theme\r
47 6.2. Your Own Locale\r
48 6.3. Your Own Data Manager\r
49 6.4. Your Own User Interface\r
50 \r
51 \r
52 1. INTRODUCTION\r
53 ===============\r
54 \r
55 Thank you for trying this Chirpy! beta version. Note that, while every feature\r
56 contained in this product is functional unless stated otherwise, you may very\r
57 well run into problems here and there. However, in most cases, there's probably\r
58 an easy fix. You may find the following URLs helpful:\r
59 \r
60 * Trackers (Bugs, Support, Feature Requests)\r
61   http://sourceforge.net/tracker/?group_id=147270\r
62 \r
63 * Chirpy! web site\r
64   http://chirpy.sourceforge.net/\r
65 \r
66 * API Specification (mainly for developers)\r
67   http://chirpy.sourceforge.net/pod/\r
68 \r
69 \r
70 2. REQUIREMENTS\r
71 ===============\r
72 \r
73 To install Chirpy!, you'll need web space that gives you access to Perl 5.8 and\r
74 a SQL server running MySQL 4.1 or higher. Those version numbers are expected\r
75 to drop a little in an upcoming version.\r
76 \r
77 In addition, you'll need these Perl modules:\r
78 \r
79 Carp                Data::Dumper        HTML::Template\r
80 Digest::MD5         DBD::mysql          HTTP::Date\r
81 Encode              DBI                 URI::Escape\r
82 POSIX               Storable\r
83 \r
84 It seems like a long list, but most of them are common and come with standard\r
85 distributions of Perl. Other modules will need to be installed separately; you\r
86 should probably ask your host about that. If any of these modules are missing,\r
87 Chirpy! will not work.\r
88 \r
89 In addition, Chirpy! uses the CGI::Carp module for verbose error reporting,\r
90 which makes problems easier to trace. While this module is also really common,\r
91 you can drop the dependency by removing statements containing "CGI::Carp" or\r
92 "set_message" from the scripts.\r
93 \r
94 \r
95 3. INSTALLATION\r
96 ===============\r
97 \r
98 If all the requirements are met, you are ready to begin the installation of\r
99 Chirpy!. Let's go!\r
100 \r
101 3.1. Copy files\r
102 ---------------\r
103 \r
104 Since you're reading this file, we'll assume that you've already extracted the\r
105 entire installation package.\r
106 \r
107 First, we'll take a quick look at the contents of the package. You should have\r
108 the following directories and files in the root:\r
109 \r
110 res/                The resources directory. Resources are public files that\r
111                     are required by themes, such as images and style sheets.\r
112 src/                The source directory. Contains all the necessary files to\r
113                     run Chirpy!, including its modules, locales, templates and\r
114                     configuration file.\r
115 util/               Contains some utilities that you may find useful while\r
116                     installing or using Chirpy!.\r
117 .htaccess           Has some directives that enable short URLs. Covered later\r
118                     in this document.\r
119 changelog.txt       All the stuff that's changed between Chirpy! releases.\r
120 index.cgi           The main script. Will be the only URL that is accessed\r
121                     directly by visitors.\r
122 install.txt         This document.\r
123 license.txt         The GNU General Public License, under which Chirpy! is\r
124                     distributed.\r
125 \r
126 Now, we're going the copy the files to a public path on the web server. This is\r
127 usually done using an FTP client.\r
128 \r
129 As for the files in the package root directory, the only one you really need is\r
130 index.cgi. Since this is a Perl script, it has to be inside a path where the\r
131 server allows execution of scripts. Most servers these days will allow that\r
132 anywhere, but yours might require that you put it inside a cgi-bin/ directory,\r
133 which may even be outside the document root on the FTP server. This is no\r
134 problem--just make sure it wants to execute it and not display the contents.\r
135 \r
136 The index.cgi file needs some attributes. This is done by issueing a SITE CHMOD\r
137 command on the FTP server. If you use a graphical FTP client, you can probably\r
138 right-click on the file and tick off the necessary attributes. They are:\r
139 \r
140                     Owner     READ      WRITE     EXECUTE\r
141                     Group     READ      -         EXECUTE\r
142                     Others    READ      -         EXECUTE\r
143 \r
144 This translates to the string representation "rwxr-xr-x" or, numerically, 755\r
145 on UNIX systems. On most systems, this step is essential. You will get an error\r
146 page if you fail to change the file's attributes. Also, if you are using an FTP\r
147 client, make sure you have uploaded index.cgi in ASCII (text) mode, not image\r
148 (binary).\r
149 \r
150 You may want to copy the .htaccess file from the package root as well. Make\r
151 sure you don't confuse it with the one in the src/ directory! The one covered\r
152 here allows you to use short URLs, which are easy to remember, using the\r
153 mod_rewrite Apache module. To use that option, you will need to run Chirpy! on\r
154 an Apache web server that has the mod_rewrite module. Note that, while short\r
155 URLs will not work if mod_rewrite is not enabled, it should be safe to have the\r
156 .htaccess file there anyway, since it checks for the module first. Moreover, it\r
157 also attempts to block access to the configuration file, so you might want to\r
158 have it anyway; we will cover that configuration file in a moment.\r
159 \r
160 The res/ directory only holds static files and should reside in a public path\r
161 on the server, like <http://www.yourserver.com/chirpy/res>. You can upload it\r
162 anywhere, even on a different server. We'll need the URL later for the\r
163 configuration.\r
164 \r
165 Next up: the src/ directory. This one does not have to be publicly accessible\r
166 and for security reasons, it really shouldn't be either. Chirpy! takes some\r
167 precautions to disallow access to it by placing a .htaccess file in it, that\r
168 holds code specific to the Apache web server. However, placing the directory\r
169 outside the document root (if possible) is a MUCH safer choice.\r
170 Alternatively, you can keep chirpy.ini, the configuration file, which we will\r
171 cover later in this document, outside the document root and the src/ directory.\r
172 \r
173 Inside the src/ directory, you will find a directory called cache/. Make sure\r
174 it is empty. Also, it needs to be world-writable, i.e. its attributes must be\r
175 set to "rwxrwxrwx" or 777.\r
176 \r
177 The util/ directory should NOT be uploaded. You are however likely to need the\r
178 setup.pl script inside it, but we'll get to that in a moment.\r
179 \r
180 That covers uploading the files--almost. We'll need to upload a configuration\r
181 file at the end of the next step.\r
182 \r
183 3.2. Configure\r
184 --------------\r
185 \r
186 Chirpy! stores its configuration in a standard .INI file, a basic format which\r
187 is common on Windows systems. In this step, we'll create such a configuration\r
188 file.\r
189 \r
190 By default, Chirpy! looks for chirpy.ini in the working directory (which is\r
191 where you put index.cgi) and inside the src/ directory if it is directly inside\r
192 the working directory. Otherwise, you will have to edit index.cgi. As explained\r
193 above, that little bit of editing is recommended, so your configuration file\r
194 resides outside the public domain. After all, it will contain your MySQL server\r
195 password, and we don't want visitors to read that, now, do we?\r
196 \r
197 Right, let's create that chirpy.ini file now. Here is a basic example:\r
198 \r
199 -------------------------------------------------------------------------------\r
200 [general]\r
201 title=My Little QDB\r
202 description=A place for my quotes\r
203 base_path=./src\r
204 locale=en-US\r
205 rating_limit_count=2\r
206 rating_limit_time=60\r
207 update_check=1\r
208 \r
209 [data]\r
210 type=MySQL\r
211 mysql.hostname=localhost\r
212 mysql.port=3306\r
213 mysql.username=my_username\r
214 mysql.password=my_password\r
215 mysql.database=my_database\r
216 mysql.prefix=chirpy_\r
217 \r
218 [ui]\r
219 type=WebApp\r
220 date_time_format=%Y-%m-%d %H:%M GMT\r
221 date_format=%Y-%m-%d\r
222 time_format=%H:%M GMT\r
223 use_gmt=1\r
224 quotes_per_page=10\r
225 recent_news_items=3\r
226 moderation_queue_public=1\r
227 tag_cloud_logarithmic=1\r
228 webapp.webmaster_name=John Doe\r
229 webapp.webmaster_email=you@yourserver.com\r
230 webapp.site_url=http://www.yourserver.com/cgi-bin/chirpy\r
231 webapp.resources_url=http://www.yourserver.com/chirpy/res\r
232 webapp.theme=default\r
233 webapp.welcome_text_file=welcome.html\r
234 webapp.cookie_domain=yourserver.com\r
235 webapp.cookie_path=/cgi-bin/chirpy\r
236 webapp.session_expiry=+3d\r
237 webapp.enable_short_urls=0\r
238 webapp.enable_feeds=0\r
239 webapp.quotes_per_feed=50\r
240 webapp.enable_gzip=0\r
241 webapp.enable_autolink=0\r
242 -------------------------------------------------------------------------------\r
243 \r
244 A lot of the values don't look very interesting right now, but we'll have to\r
245 change some of the others.\r
246 \r
247 3.2.1. The [general] Section\r
248 ----------------------------\r
249 \r
250 title               Change this value to the title you want your QDB to have.\r
251 description         Enter a brief description of the purpose of your QDB.\r
252 base_path           Enter the absolute or relative path to the src/ directory\r
253                     here. When using relative paths, this is again relative to\r
254                     the directory where index.cgi is.\r
255 update_check        Set this to 1 to tell Chirpy! to automatically check for\r
256                     updates periodically. Only site owners will be informed of\r
257                     available updates. This feature requires that libwww-perl\r
258                     (LWP) be installed; if it is not, Chirpy! will just show\r
259                     you an informative error message.\r
260 \r
261 3.2.2. The [data] Section\r
262 -------------------------\r
263 \r
264 mysql.hostname      Enter the name of the MySQL server here. Usually, this will\r
265                     be "localhost".\r
266 mysql.port          Enter the port the MySQL server uses. The default is 3306.\r
267 mysql.username      Enter your MySQL username. This is not necessarily the same\r
268                     as your regular username.\r
269 mysql.password      Enter your MySQL password. This is not necessarily the same\r
270                     as your regular password.\r
271 mysql.database      Enter the name of the MySQL database Chirpy! should use. If\r
272                     it does not exist, you need to create it first. Do not\r
273                     create any tables; Chirpy! will do that for you.\r
274 mysql.prefix        If you only have one MySQL database, Chirpy! can make its\r
275                     tables easy to find by prefixing their names with the text\r
276                     you enter here. The default "chirpy_" is a wise choice.\r
277 \r
278 3.2.3. The [ui] Section\r
279 -----------------------\r
280 \r
281 webapp.webmaster_name\r
282                     Your name.\r
283 webapp.webmaster_email\r
284                     Your e-mail address. Don't worry about spam, Chirpy! will\r
285                     use some fancy tricks to hide it.\r
286 webapp.site_url     The URL where you put index.cgi.\r
287 webapp.resources_url\r
288                     The URL where you put the res/ directory.\r
289 webapp.cookie_domain\r
290                     Essentially the domain name (without the www prefix) from\r
291                     your site's URL. This will be used to store cookies.\r
292 webapp.cookie_path  The part that comes after the domain in the site URL. This\r
293                     will also be used to store cookies.\r
294 webapp.enable_short_urls\r
295                     Change this to 1 to enable the short URLs feature described\r
296                     above. If you get "Not Found" errors while browsing the QDB\r
297                     later, you should turn it off.\r
298 webapp.enable_feeds Chirpy! can offer an RSS 2.0 feed and an Atom 1.0 feed of\r
299                     the Quotes of the Week, so visitors can syndicate them. If\r
300                     you want to enable those, set this to 1.\r
301 webapp.quotes_per_feed\r
302                     This is the maximum number of quotes to include in a feed.\r
303                     In theory, Chirpy! can provide a content feed for any page,\r
304                     and since feeds do not offer "Previous"/"Next" links, this\r
305                     should be a sensible number. The default is 50.\r
306 webapp.enable_gzip  Chirpy! can greatly decrease bandwidth usage by compressing\r
307                     output on the fly if the browser supports it. Set this to 1\r
308                     to enable that. It requires the Compress::Zlib Perl module.\r
309 webapp.enable_autolink\r
310                     Change this to 1 to automatically turn URLs and e-mail\r
311                     addresses in quote bodies into hyperlinks. This feature is\r
312                     still sort of experimental, but should work fine.\r
313 webapp.captcha_provider\r
314                     If you wish to prevent malicious users from spamming the\r
315                     quote submission page, you will want to use captcha images.\r
316                     This parameter sets the captcha provider, which will be\r
317                     Authen_Captcha in most cases. Then Authen_Captcha provider\r
318                     relies on Authen::Captcha being installed.\r
319 \r
320 You may want to turn the captcha feature off at first, so you can test-drive\r
321 Chirpy!'s other features. Configuring the captcha feature should be easy in the\r
322 case of Authen_Captcha. The alternative is to use GD_SecurityImage. Support for\r
323 that one is preliminary for now. If you are interested in using it, please\r
324 consult the appropriate documentation.\r
325 \r
326 That covers the configuration file. Save it as chirpy.ini and, as stressed\r
327 before, try to store it at a location on the server which cannot be accessed\r
328 using a Web browser.\r
329 \r
330 Now, we'll have to modify index.cgi a little to tell it where to find the\r
331 configuration file. Again, it looks for chirpy.ini in the working directory and\r
332 inside src/, but hopefully, it won't be there. So we'll just open index.cgi in\r
333 a text editor and change the line\r
334 \r
335   chirpy;\r
336 \r
337 to the following:\r
338 \r
339   chirpy('/path/to/chirpy.ini');\r
340 \r
341 Again, you can use either an absolute path or a path relative to the working\r
342 directory. You'll also need this path in the next step.\r
343 \r
344 While we're editing index.cgi, there are two more things you might have to\r
345 change. The first is the path to the modules/ directory inside src/. This path\r
346 is stored like:\r
347 \r
348   unshift @INC, 'src/modules';\r
349 \r
350 If you have not placed the src/ directory in the same directory as index.cgi,\r
351 update the path so Perl can find the Chirpy! modules.\r
352 \r
353 The other thing you might have to change is the path to Perl itself. Most\r
354 servers have it at /usr/bin/perl, but if yours doesn't, change the first line\r
355 of index.cgi to "#!" followed by the exact path to Perl.\r
356 \r
357 3.3. Setup\r
358 ----------\r
359 \r
360 Now that all the files are there, we'll grab setup.pl from the util/ directory\r
361 and open it in a text editor. Look for the line that reads\r
362 \r
363   my $ch = new Chirpy();\r
364 \r
365 and change that to\r
366 \r
367   my $ch = new Chirpy('/path/to/chirpy.ini');\r
368 \r
369 using the same path you entered in index.cgi. In addition, you will have to\r
370 update the path to src/modules/ and Perl itself again, if you had to do so for\r
371 index.cgi.\r
372 \r
373 Now, upload setup.pl to the directory where index.cgi resides and change its\r
374 attributes so they are the same as index.cgi's; as described above, they should\r
375 be rwxr-xr-x (755). Again, since this is a Perl script, upload in ASCII mode!\r
376 \r
377 Now, we're going to call your Web browser into action. Open it and surf to the\r
378 URL where setup.pl should be now, e.g.\r
379 \r
380   http://www.yourserver.com/cgi-bin/chirpy/setup.pl\r
381 \r
382 That should give you a basic page, welcoming you to the setup procedure. If\r
383 not, let's go over a few common problems ...\r
384 \r
385 - If you get the source code of setup.pl or maybe a download window, the server\r
386   doesn't allow execution of Perl scripts in that directory. You'll probably\r
387   need to use the cgi-bin directory instead.\r
388 \r
389 - If you get a Forbidden error, you probably didn't change the script's\r
390   attributes properly, as described above.\r
391 \r
392 - If you get a fairly verbose error that has line numbers and lots of weird\r
393   characters and other stuff that confuses you in it, the server executed the\r
394   script, but it crashed somewhere along the way. Something may have gone wrong\r
395   with the upload of one or more files; upload them again. If that doesn't do\r
396   any good, paste the error message at the Support Tracker, to which you can\r
397   find the URL at the start of this document.\r
398 \r
399 - If you get a generic "Internal Server Error" page, the server most likely\r
400   failed to execute the script at an earlier stage. Some files may have gotten\r
401   corrupted in the upload process; try uploading them again. If that doesn't\r
402   help, go over the text above to see if you didn't miss anything. If problems\r
403   persist, your host can give you a copy of the server's error log, which may\r
404   tell you more. If you can get an error message from the log, you can post\r
405   that at the Support Tracker; without it, the error will be nearly impossible\r
406   to trace.\r
407 \r
408 Assuming you've reached the setup page now, you get to decide if you want to\r
409 keep your existing installation if any. If you're installing Chirpy! for the\r
410 first time, you should choose to keep data, since it's faster. That should give\r
411 you a page with a basic event log for the setup procedure. If it tells you the\r
412 setup procedure has been completed, you can go to the next step now. If not,\r
413 take a look at the error and see if you can fix things. If not, try the Support\r
414 Tracker for assistance.\r
415 \r
416 3.4. Import\r
417 -----------\r
418 \r
419 This step is optional. It only applies if you have the Rash Quote Management\r
420 System installed and you want to migrate its data to Chirpy!. If you have no\r
421 idea what this is about, just skip this step.\r
422 \r
423 To import Rash's data, grab chirpy_rqms_import.php from the util/ directory.\r
424 Open it in a text editor and edit the configuration values at the start of the\r
425 script. Then place it in the directory where you installed Rash, so it can find \r
426 config.php. Surf to chirpy_rqms_import.php and everything should be clear from\r
427 there. If anything goes wrong, try the Support Tracker.\r
428 \r
429 \r
430 4. UPGRADING\r
431 ============\r
432 \r
433 If you are upgrading from Chirpy! version 0.1 or 0.2, you should just move the\r
434 updated setup.pl script from the "util" directory into Chirpy!'s root directory\r
435 for a second, make it executable, and surf to it. Chirpy! will then ask you if\r
436 you want to perform a fresh installation or an upgrade. Now, DO *NOT* CLICK ON\r
437 "FRESH INSTALLATION," because you would lose all your quotes, accounts, etc.\r
438 Instead, click the "UPGRADE" button, wait for the page to load, watch Chirpy!\r
439 inform you of the successful upgrade, and remove setup.pl again.\r
440 \r
441 Additionally, as Chirpy! 0.3 offers quite a couple of new features, you will\r
442 probably want to play with those. Most of them just come down to adding a line\r
443 in the configuration file. For captchas, you will need to create a couple of\r
444 directories; just scroll back to section 3.2, where the configuration file is\r
445 explained--it's all there. Enjoy!\r
446 \r
447 \r
448 5. RUN CHIRPY!\r
449 ==============\r
450  _____________________________________________________________________________\r
451 |                                                                             |\r
452 |    !!! DON'T FORGET TO REMOVE THE SETUP SCRIPT FROM THE SERVER FIRST !!!    |\r
453 |_____________________________________________________________________________|\r
454 \r
455 By now, the setup script should have directed you to your brand new Chirpy!\r
456 installation already. If not, append /index.cgi to your site URL and open that\r
457 URL. That should give you a cute little start page. You should be able to leave\r
458 off index.cgi in the URL now--try it. If it doesn't work, you should definitely\r
459 turn short URLs off. If something else goes wrong, you should try the Support\r
460 Tracker; the URL is at the beginning of this file.\r
461 \r
462 Now, you're pretty much finished. Except that you should change the default\r
463 password. Surf to the administration section, log in as "superuser" with the\r
464 password "password" (if you didn't poke at setup.pl already) and click on the\r
465 "Manage Accounts" option. Select the "superuser" account and modify it.\r
466 \r
467 That concludes the installation of Chirpy!. I hope you'll enjoy it. If you run\r
468 into a problem or you'd like to see a new feature in the next release, surf to\r
469 the Trackers.\r
470 \r
471 Congratulations on a successful installation!\r
472 \r
473 \r
474 6. NEXT STEPS\r
475 =============\r
476 \r
477 Now that you've got a working Chirpy! installation, you can tweak it to your\r
478 liking. Most of this is done from the configuration file. If you want to change\r
479 the welcome message, you just edit the file welcome.html in the src/ directory,\r
480 which is actually a template.\r
481 \r
482 As Chirpy! is a work in progress, you can expect a lot more documentation on\r
483 customizing it in future releases. In the mean time, if you want to do more\r
484 advanced tweaking, here are a few possible scenarios:\r
485 \r
486 6.1. Your Own Theme\r
487 -------------------\r
488 \r
489 The easiest way to do this is to copy the existing "default" theme and modify\r
490 it, after which you change webapp.theme in the configuration file to use the\r
491 new theme. A theme is nothing but two directories named after it: the one in\r
492 src/themes/ holds the templates for the theme, the one in res/ holds its\r
493 resources. The template filenames are predefined, so you need to keep those\r
494 intact. The templates are parsed by the HTML::Template Perl module, so you will\r
495 probably have to look at its documentation for a second--or you could just\r
496 learn to use it by looking at the default theme's source code. The manual page\r
497 for HTML::Template can be found at\r
498 \r
499   http://search.cpan.org/dist/HTML-Template/Template.pm\r
500 \r
501 6.2. Your Own Locale\r
502 --------------------\r
503 \r
504 You might want Chirpy! in your own language, and you can have it too. If you\r
505 look in the src/locales/ directory, you'll see that locales are actually just\r
506 INI files. Each locale string, along with some basic instructions for locale\r
507 creation, is documented in the POD, located at the URL at the start of this\r
508 document.\r
509 \r
510 6.3. Your Own Data Manager\r
511 --------------------------\r
512 \r
513 Chirpy! is extremely modular. If you'd rather have it store its data in your\r
514 choice of database, you are free to implement the Chirpy::DataManager class.\r
515 Its API is explained in the POD, which is available at the start of this\r
516 document or by typing "perldoc Chirpy::DataManager" from a console or command\r
517 prompt, if you have Perl installed.\r
518 \r
519 6.4. Your Own User Interface\r
520 ----------------------------\r
521 \r
522 Apart from creating a backend, you can also write your own frontend class. This\r
523 class should implement Chirpy::UI. Unfortunately, the API documentation for it\r
524 is not yet available. Note that if your UI would be a web site, you should\r
525 probably just create a Chirpy::UI::WebApp theme as described in 5.1.\r
526 \r
527 If you've created a theme, a locale, a data manager or a UI, please share your\r
528 work with the community! E-mail it to me at ceetee@users.sourceforge.net and it\r
529 might be included in the next Chirpy! release by default. Obviously, you would\r
530 get credit for it.\r
531 \r
532 \r
533 ###############################################################################