nucleus/documentation/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4         <!-- $Id: index.html 1457 2010-10-26 15:47:41Z ftruscot $ -->
   5         <title>Nucleus CMS - Manual</title>
   6         <link rel="stylesheet" type="text/css" href="styles/manual.css" />
   7 </head>
   8 <body>
   9
  10 <div class="heading">
  11 Nucleus CMS Manual
  12 <i>(v3.3)</i>
  13 </div>
  14
  15 <div class="note">
  16 <b>Notes:</b>
  17 <ul>
  18         <li>This manual only contains information that is not already contained in the popup-help (<a href="help.html">help.html</a>) available from the administration area. This document also contains instruction for the <a href="#installation">installation</a> of Nucleus.</li>
  19         <li>If you're a developer, <a href="devdocs/index.html">extra developer documentation</a> is available.</li>
  20 </ul>
  21 </div>
  22
  23 <h1><a name="toc"></a>Table Of Contents</h1>
  24
  25 <ul>
  26         <li><a href="#about">About Nucleus CMS</a></li>
  27         <li><a href="#license">License: GPL</a></li>
  28         <li><a href="#installation">Installation</a></li>
  29         <li><a href="skins.html">Modifying skins and templates</a> (separate file)</li>
  30         <li><a href="#security">Security Aspects</a></li>
  31         <li><a href="#performance">Performance Aspects</a></li>
  32 <!-- <li><a href="#import">Importing from other tools</a></li> -->
  33         <li><a href="#comments">What's allowed/disallowed in comments?</a></li>
  34         <li><a href="#xmlrpc">XML-RPC Interface</a></li>
  35         <li><a href="#trouble">Troubleshooting (FAQ)</a></li>
  36         <li><a href="tips.html">Tips &amp; Suggestions</a> (separate file)</li>
  37         <li><a href="#known">Known Problems</a></li>
  38         <li><a href="history.html">Version History</a> (separate file)</li>
  39         <li><a href="#credits">Credits &amp; Thanks</a></li>
  40 </ul>
  41
  42 <h1>About Nucleus <a name="about" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
  43
  44 <p>
  45 Nucleus is a Content Management System (CMS): a powerful set of PHP scripts that allow you to maintain one or more weblogs or online journals. A short summary of the most important features is given below:
  46 </p>
  47
  48 <ul>
  49         <li>Runs on your own server</li>
  50         <li>One or more weblogs, even on the same page</li>
  51         <li>Plugin-interface to add extra functionality</li>
  52         <li>Comments</li>
  53         <li>Archives</li>
  54         <li>Categories</li>
  55         <li>Search</li>
  56         <li>Multiple authors</li>
  57         <li>Future items</li>
  58         <li>Drafts</li>
  59         <li>Extensive administration area</li>
  60         <li>Media library and file upload</li>
  61         <li>Fully customizable skins and templates</li>
  62         <li>Skin import/export</li>
  63         <li>Banlist against commenting system abuse</li>
  64         <li>RSS syndication</li>
  65         <li>Easy installation</li>
  66         <li>Easy backups</li>
  67         <li>XML-RPC interface (implementing the <a href="http://plant.blogger.com/api/">Blogger API</a> and <a href="http://www.xmlrpc.com/metaWeblogApi">metaWeblog API</a>)</li>
  68         <li>XHTML-ready</li>
  69         <li>Tools to import Blogger and GreyMatter blogs</li>
  70         <li>...</li>
  71 </ul>
  72
  73 <p>
  74 Requirements in order to run Nucleus: <small>(If you don't know if you fit the requirements, ask your system administrator)</small>
  75 </p>
  76
  77 <ul>
  78         <li><a href="http://www.php.net/">PHP</a> (version 5.0.0 or higher, may still work on version 4.0.6 or higher)</li>
  79         <li>Access to a <a href="http://www.mysql.com/">MySQL</a> database (version 4 or higher)</li>
  80         <li>Some <acronym title="Hypertext Markup Language">HTML</acronym> and <acronym title="Cascading Style Sheets">CSS</acronym> knowledge, to edit skins and templates</li>
  81 </ul>
  82
  83
  84
  85 <p>
  86 Nucleus is intended for the people that want full control and 'tweakability' over their sites. If you're just looking for a very simple way to put up a site, or don't know any HTML, you might want to use a 'simpler' service such as <a href="http://www.blogger.com/">Blogger</a>.
  87 </p>
  88
  89
  90
  91
  92 <a name="license"></a>
  93 <h1>License <a name="copyright" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
  94
  95 <p>
  96 Nucleus: PHP/MySQL Weblog CMS (http://nucleuscms.org/)
  97 <br />
  98 Copyright (C) 2002-2007 The Nucleus Group
  99 </p>
 100
 101 <p>This program is free software; you can redistribute it and/or
 102 modify it under the terms of the GNU General Public License
 103 as published by the Free Software Foundation; either version 2
 104 of the License, or (at your option) any later version.</p>
 105
 106 <p>This program is distributed in the hope that it will be useful,
 107 but WITHOUT ANY WARRANTY; without even the implied warranty of
 108 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 109 GNU General Public License for more details.</p>
 110
 111 <p>You should have received a <a href="../../license.txt">copy of the GNU General Public License</a>
 112 along with this program; if not, write to the Free Software
 113 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.</p>
 114
 115 <p>
 116 Your possession of this software signifies that you agree to these terms. Please delete your copy of this software if you don't agree to these terms.
 117 </p>
 118
 119
 120 <h1>Installation <a name="installation" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 121
 122 <div class="note">
 123 <b>Note:</b> If you are upgrading, you should see the <a href="http://www.nucleuscms.org/upgrade.php">upgrade instructions</a> on the Nucleus website.
 124 </div>
 125
 126 <p>
 127 Installing Nucleus is done through some steps:
 128 </p>
 129
 130 <h2>1. Unzip</h2>
 131
 132 <p>
 133 Unzip all files to a directory of your computer. Make sure the path names are used when unzipping. You should end up with the following directory structure (* stands for a number of files):
 134 </p>
 135
 136 <pre>
 137 /*                           (main files for site)
 138 /nucleus/*                   (main files for admin-area)
 139 /nucleus/javascript/*        (javascript helper scripts)
 140 /nucleus/libs/*              (Nucleus core libs)
 141 /nucleus/locales/*          (definitions of locales)
 142 /nucleus/plugins/*           (plugin-dir)
 143 /nucleus/xmlrpc/*            (XML-RPC interface)
 144 /nucleus/documentation/*     (Documentation + admin-area help)
 145 /nucleus/styles/*            (stylesheets for docs &amp; admin-area)
 146 /nucleus/forms/*             (skeletons for commentforms etc)
 147 /extra/*                     (extra goodies, e.g. needed files to enable fancy URLs)
 148 /skins/*                     (skins directory [imported skins will go here])
 149 /media/*                     (media library directory [emtpy])
 150 </pre>
 151
 152
 153 <h2>2. Upload files</h2>
 154
 155 <p>
 156 Upload all files to your server, using your favorite FTP program. Make sure to upload .php files in ASCII mode! It might not work otherwise.
 157 </p>
 158
 159 <h3>Optional:</h3>
 160
 161 <ol>
 162         <li>
 163                 To make your install process even easier, you can change the file permissions on <em>config.php</em> to <strong>666</strong>. This way, the install script will be able to update it automatically instead of you having it to do manually. (<a href="tips.html#filepermissions">Quick guide on how to change file permissions</a>)
 164         </li>
 165         <li>
 166                 If you want to use file upload, you'll need to add write permissions to the /media/ directory. This is needed in order to allow PHP to write uploaded files into that directory. The directory should be <i>chmod</i>ded to <strong>777</strong> (<a href="tips.html#filepermissions">Quick guide on how to change file permissions</a>). (If you have root access, you can instead <tt>chgrp</tt> the directory to the user that is running the <tt>httpd</tt> process (usually <tt>httpd</tt> or <tt>nobody</tt>, then <tt>chmod 775</tt> the directory).
 167         </li>
 168         <li>
 169                 If you want to use the SkinFiles plugin to edit files, you'll need to change the permissions on all files and directories under the /skins/ directory. To be able to edit files, they should be <i>chmod</i>ded to <strong>666</strong> (<a href="tips.html#filepermissions">Quick guide on how to change file permissions</a>). To be able to create new files or directories, the parent directory should be <i>chmod</i>ded to <strong>777</strong>.
 170         </li>
 171 </ol>
 172
 173
 174 <h2>3. Run install.php</h2>
 175
 176 <p>
 177 Open your web browser open the URL below, where you adapt the <i>yoursite</i> and <i>yourpath</i> parts.
 178 </p>
 179
 180 <pre>
 181 http://www.yoursite.com/yourpath/install.php
 182 </pre>
 183
 184 <p>
 185 This install-script will prompt you for some information, and perform most of the installation for you. When everything has succeeded, <i>install.php</i> will provide you with further instructions. (you'll still need to delete some files manually)
 186 </p>
 187
 188 <div class="note">
 189 <b>Note:</b> When you open <i>install.php</i> in your browser and you see the text "If you see this text in your browser...", or you are prompted to download 'install.php', then your web server does not support PHP, and you won't be able to run Nucleus there.
 190 </div>
 191
 192 <h2>4. Done!</h2>
 193
 194 <p>
 195 You should now be able to visit your site at http://yoursite.com/weblog/ (or whatever URL maps to the location where you uploaded the Nucleus site main files)
 196 </p>
 197
 198
 199
 200
 201
 202
 203
 204 <h1>Security Aspects <a name="security" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 205
 206 <h2>mySQL passwords</h2>
 207
 208 <p>
 209 Since Nucleus needs to connect to a mySQL database from a PHP-script, the password for that database must be stored inside a PHP-file. On multi-user systems, this might cause an unevitable security risk: On some systems, other users will be able to read your login information. You might want to contact your system operator to find out how secure it is to store sensible information inside PHP-scripts.
 210 </p>
 211
 212 <p>
 213 The problem above is common to all PHP scripts that need to connect to a database. As a user, there's usually nothing you can do about it in order to make things 100% secure. We just want you to be aware of this potential danger.
 214 </p>
 215
 216 <h2>Cookies</h2>
 217
 218 <p>
 219 Nucleus uses cookies to store user login information. This could cause a security risk when your cookies are stolen. Although your password is not derivable from the cookie <small>(the values stored in the cookie are the username and a randomly generated string)</small>, there could be ways to 'fake' the cookie on another computer and thus to get logged in.
 220 </p>
 221
 222 <h2>Media dir</h2>
 223
 224 <p>
 225 When you want to enable file upload, you'll need to set the permissions of the media dir to 777, which means that <b>everyone</b> on that server will be able to delete/add/... files. The reason why this is needed, is that PHP mostly runs as the httpd user, and that user needs to be able to access this dir and write to it. Here also, there's no way around this.
 226 </p>
 227
 228
 229
 230
 231
 232 <h1>Performance Aspects <a name="performance" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 233
 234 <p>
 235 Contradictory to some other weblog/online journal scripts, Nucleus does not generate a static version of all items. This means that every time a page is requested, the PHP parser is called and the database is accessed to dynamically create the requested page.
 236 </p>
 237
 238 <p>
 239 For small web sites, this should not cause any problem. For web sites that get dozens of hits per second, the effect on the systems performance isn't really known. So far, no problems have been reported by Nucleus users (some are running pretty big sites on it, with 30 or more weblogs on a single installation).
 240 </p>
 241
 242
 243
 244
 245 <!--
 246 <h1>Importing From Other Tools <a name="import" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 247
 248 <p>
 249 Nucleus contains some conversion scripts that allow you to import the data from your 'old' weblog tool into your Nucleus weblog. No data is destroyed during this process.
 250 </p>
 251
 252 <p>
 253 More information is available on the <a href="http://www.nucleuscms.org/convert.php">Nucleus website</a>. At the time of release, the only available conversion tools are those for Blogger and GreyMatter blogs.
 254 </p>
 255 -->
 256
 257
 258 <h1>What's allowed/disallowed in comments? <a name="comments" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 259
 260 <p>
 261 Nucleus has some built-in rules concerning comments:
 262 </p>
 263
 264 <ul>
 265         <li>words longer than 90 characters are not allowed (why: layout might get messed up when people do that) </li>
 266         <li>the actual comment should be at least 3 characters long</li>
 267         <li>comments cannot be longer than 5000 characters </li>
 268         <li>guests need to enter a username of at least 2 characters </li>
 269         <li>guests cannot use quotes or newlines in username/email </li>
 270         <li>each sequence of 3 newlines in the body gets replaced by a single newline (why: layout)</li>
 271         <li>HTML tags are replaced by entities</li>
 272         <li>the comment is trimmed (leading and trailing whitespace is left of)</li>
 273         <li>URLs are 'hreffed'. To avoid layout mess-ups, the URLs are shortened.</li>
 274 </ul>
 275
 276 <p>
 277 As for now, all of these rules and parameters are hardwired into the code.
 278 </p>
 279
 280
 281
 282
 283
 284
 285 <h1>XML-RPC Interface <a name="xmlrpc" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 286
 287 <div class="note">
 288 The URL for the Nucleus XML-RPC interface is:
 289 <br />
 290 <b>http://www.yourserver.com/yourpath/nucleus/xmlrpc/server.php</b>
 291 </div>
 292
 293 <p>
 294 <a href="http://www.xmlrpc.com/">XML-RPC</a> is a format for remote calls using XML messages. Sounds complex, but implementing an XML-RPC interface into an application allows other services to communicate with it.
 295 </p>
 296
 297 <p>
 298 Currently, there are three APIs supported: the <a href="http://plant.blogger.com/api/">Blogger API</a>, the <a href="http://www.xmlrpc.com/metaWeblogApi">metaWeblog API</a>, and the <a href="http://www.movabletype.org/docs/mtmanual_programmatic.html#xmlrpc%20api">Movable Type API</a>. If you want an examples of a client that uses these interfaces, try <a href="http://www.wbloggar.com/">w.Bloggar</a> (Windows) or <a href="http://www.kung-foo.tv/ecto/">Ecto</a> (MacOS).
 299 </p>
 300
 301 <p>
 302 The available calls to the interface are described in the development documentation, which can be <a href="http://nucleuscms.org/download.php">separately downloaded</a>, or <a href="http://nucleuscms.org/documentation/devdocs/xmlrpc.html">viewed online</a>.
 303 </p>
 304
 305
 306
 307 <h1>Troubleshooting (FAQ) <a name="trouble" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 308
 309 <p>Below, some of the most common problems with and questions about Nucleus are answered. Please read these first before you ask for help. In many cases, the solution can be found here.
 310 </p>
 311
 312 <div class="faq">
 313 <div class="question">I get an error: <q>Cannot send headers. Headers already sent...</q></div>
 314 <div class="answer">
 315 This problem is usually caused by whitespace at the beginning or end of <code>config.php</code>. Check if it has spaces or newlines before the starting <tt>&lt;?</tt> or after the ending <tt>?&gt;</tt>. If there are, remove them. The problem can also have to do with spaces in the translation file or one of the installed plugins.
 316 </div>
 317 </div>
 318
 319 <div class="faq">
 320 <div class="question">When I try to run install.php, I'm prompted if I want to download install.php</div>
 321 <div class="answer">Your web server is not set up to support PHP scripts. You won't be able to install Nucleus on such a system.</div>
 322 </div>
 323
 324 <div class="faq">
 325 <div class="question">When I try to visit my website, I get a 'Connection Error'. Why?</div>
 326 <div class="answer">
 327 The reason why this error is shown is that Nucleus cannot connect to your database server for one reason or another, or it cannot select the database. One possible reason is that your login information in <i>config.php</i> is incorrect. Another is that the mySQL server is down.
 328 </div>
 329 </div>
 330
 331 <div class="faq">
 332 <div class="question">I can't get my update file to work!</div>
 333 <div class="answer">
 334 File permissions need to be set correctly in order for the update file to work. The update file also needs to exist prior to changing the blogsettings. (e.g. you can create an empty file and upload it). About the file permissions, make sure the update file is <i>chmod</i>ded to 666 and the directories are <i>chmod</i>ded to 755. (<a href="tips.html#filepermissions">Quick guide on changing file permissions</a>)
 335 </div>
 336 </div>
 337
 338 <div class="faq">
 339 <div class="question">I don't want the XML-RPC interface to be available</div>
 340 <div class="answer">You can simply delete the xmlrpc/ directory without causing trouble.</div>
 341 </div>
 342
 343 <div class="faq">
 344 <div class="question">I don't want RSS syndication (headlines) to be available</div>
 345 <div class="answer">You can safely delete the xml-rss.php (headlines.php) file and the 'xmlrss' (headlines) skin/template</div>
 346 </div>
 347
 348
 349 <h1>Known Problems <a name="known" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 350
 351 <p>Some known issues/bugs:
 352 </p>
 353
 354 <ul>
 355         <li>At the time of release, there are officially supported blog conversion tools available for Nucleus v3.3. We do have a set of code with which you can start, and are providing <a href="http://nucleuscms.org/convert.php">pointers to the import tools created by others</a>. A good starting point is also the Nucleus Forum section <a href="http://forum.nucleuscms.org/viewforum.php?f=17">Import Questions</a>. Because all blog system have a different structure it isn't possible to convert each system in another without a possible loss of information. The script authors try to minimize troubles and loss of information.</li>
 356         <li>Ctrl + Shift + A shortcut might conflict with ICQ/Trillian</li>
 357         <li>When PHP is running in SAFE mode, it's very likely that there will be problems when using the media directory (Nucleus will not be able to automatically detect image sizes, or disallow uploading)</li>
 358         <li>Entities can get messed up in the RSS channel (e.g. &amp;amp; becomes &amp;amp;amp;)</li>
 359         <li>The notify-address option in blogsettings has a preset limit of 255 chars, which means you can't put too many e-mail addresses in there.</li>
 360         <li>Live preview doesn't work correctly in Mozilla</li>
 361         <li>Internet Explorer 6 seems to be occasionally closing itsself after adding an item. The item is added, though. (it's been a while since the last complaint about that, so it <em>might</em> have disappeared)</li>
 362 </ul>
 363
 364
 365
 366 <h1>Credits &amp; Thanks <a name="credits" href="#top" class="toplink"><img src="icon-up.gif" width="15" height="15" alt="back to top" /></a></h1>
 367
 368 <p>No matter how hard we try, some people will be unintentionally overlooked in this section.</p>
 369
 370 <h2>Founder</h2>
 371
 372 <ul>
 373         <li>Wouter Demuynck</li>
 374 </ul>
 375
 376 <h2>Code submissions</h2>
 377
 378 <ul>
 379         <li>Andy Matsubara</li>
 380         <li>Armon Toubman</li>
 381         <li>Edmond Hui</li>
 382         <li>gRegor alias gregorlove</li>
 383         <li>Kai Greve alias kg</li>
 384         <li>Joel Pan alias ketsugi</li>
 385         <li>Kimitake</li>
 386         <li>Legolas</li>
 387         <li>Niels Leenheer alias rakaz</li>
 388         <li>Rodrigo Moraes</li>
 389         <li>Jeroen Budts</li>
 390         <li>Appie Verschoor alias xiffy (Fulltext search)</li>
 391         <li>Many others... (check the <a href="history.html">history</a>)</li>
 392 </ul>
 393
 394 <h2>Libraries etc</h2>
 395
 396 <ul>
 397         <li>Jeff MacMichael (NP_SkinFiles plugin)</li>
 398         <li>Ivan Fong, Roel, Moraes, Hcgtv (Nucleus 3.2 default skin)</li>
 399         <li>Plugins are written by their respective authors.</li>
 400         <li>Thanks should go out to the people that wrote translation-files for Nucleus. You can <a href="http://nucleuscms.org/languages.php">download extra translation files on the Nucleus website</a>.</li>
 401         <li>The logo (the one with the yellow rays) was created by Rodrigo Moraes</li>
 402         <li>The RSS 2.0 skin was created by <a href="http://www.xiffy.nl">Xiffy</a></li>
 403         <li>The XML-RPC interface uses the <a href="http://phpxmlrpc.sourceforge.net/">'XML-RPC for PHP'</a> implementation from <a href="http://www.usefulinc.com/">Useful Inc.</a>.</li>
 404         <li>The backup/restore code is largely inspired on the code used in <a href="http://phpbb.sourceforge.net/">phpBB</a>. </li>
 405         <li>The JavaScript code used for the instant preview was originally inspired on the code used by <a href="http://www.mijnkopthee.nl/">Mijn Kop Thee</a> <small>(dutch)</small> and <a href="http://www.milov.nl/">milov.nl</a>.</li>
 406         <li>The globe bullet next to links in the admin screen, comes from <a href="http://www.matterform.com/qbullets/legend.html">QBullets</a></li>
 407 </ul>
 408
 409 <h2>Thanks!</h2>
 410
 411 <p>
 412 Many thanks should also go to all people who have helped Nucleus to become what it is today.</p>
 413
 414 <ul>
 415         <li>A list of <a href="http://nucleuscms.org/donators.php">donators</a> is available on the Nucleus website.</li>
 416         <li>Special thanks to the <a href="http://forum.nucleuscms.org/groupcp.php?g=3">forum moderators</a> and <a href="http://forum.nucleuscms.org/memberlist.php?mode=posts&amp;order=DESC">frequent forum visitors</a>.</li>
 417 </ul>
 418
 419
 420
 421 </body>
 422 </html>