Rev Author Line No. Line
228 kaklik 1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3  
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <title>singapore - Readme</title>
7 <link rel="stylesheet" type="text/css" href="docstyle.css" />
8 </head>
9  
10 <body>
11  
12  
13 <h1>singapore v0.10.1 - Readme</h1>
14  
15 <ul>
16 <li><a href="#release">Release notes</a></li>
17 <li><a href="#history">Version history</a></li>
18 <li><a href="#license">License information</a></li>
19 <li><a href="#install">Installation</a></li>
20 <li><a href="#upgrade">Upgrading</a></li>
21 <li><a href="#managing">Gallery management</a></li>
22 <li><a href="#permissions">Help with file permissions</a></li>
23 <li><a href="#adminpermissions">The deal with admin permissions</a></li>
24 <li><a href="#users">Managing users</a></li>
25 <li><a href="#nomenclature">Naming of parts (glossary)</a></li>
26 <li><a href="Advanced.html">Advanced features</a></li>
27 <li><a href="Development.html">Developer documentation</a></li>
28 <li><a href="Translation.html">Translating singapore</a></li>
29 </ul>
30  
31  
32 <h2><a name="license">Licensing information</a></h2>
33  
34 <pre>
35 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
36 * <a href="http://www.sgal.org/">singapore</a> - Copyright 2002-6 Tamlyn Rhodes &lt;tam@zenology.co.uk&gt; *
37 * *
38 * singapore is free software; you can redistribute it and/or modify *
39 * it under the terms of the <a href="License.txt">GNU General Public License</a> as published *
40 * by the Free Software Foundation; either version 2 of the License, *
41 * or (at your option) any later version. *
42 * *
43 * singapore is distributed in the hope that it will be useful, *
44 * but WITHOUT ANY WARRANTY; without even the implied warranty *
45 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *
46 * See the GNU General Public License for more details. *
47 * *
48 * You should have received a copy of the GNU General Public License *
49 * along with this; if not, write to the Free Software Foundation, *
50 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
51 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
52 </pre>
53  
54 <p>You are kindly requested to display a link such as the following on all
55 pages generated by singapore. However in cases where this is not desirable,
56 a project donation of 20USD is considered a suitable alternative.</p>
57  
58 <p class="boxed">Powered by <a href="http://www.sgal.org/">singapore</a></p>
59  
60  
61 <h2><a name="release">Release notes</a></h2>
62  
63 <p>This is a recommended update as it addresses a critical bug in the
64 template handling that could allow an attacker to view the contents of system
65 files on the web server. Several other less severe bugs have been fixed
66 including acces control settings inheritance in the admin which should now
67 work correctly. The latest version of the 'modern' template is also included.</p>
68  
69  
70 <h2><a name="install">Installation</a></h2>
71  
72 <ol>
73 <li>Extract all the files in the archive, conserving the directory hierarchy.</li>
74  
75 <li>If you wish to change any path settings or use one of the SQL backends,
76 make the necessary changes to <code>singapore.ini</code>. If you don't know
77 why you might want to do this then you don't need to do it.</li>
78  
79 <li>Upload everything to your web server.</li>
80  
81 <li>Set file permissions. The directories that need to be made writable are:
82 <ul>
83 <li><code>data/</code> and all subdirectories and files</li>
84 <li><code>galleries/</code> and all subdirectories and files</li>
85 </ul>
86 <a href="#permissions">Help with file permissions</a>.
87 </li>
88  
89 <li>Point your browser to the <code>install/</code> directory and follow the instructions.</li>
90  
91 <li>Delete the <code>install/</code> directory to prevent unauthorised access.</li>
92  
93 <li>Log into the admin section and change the password. The username is
94 <code>admin</code> and the default password is <code>password</code>.</li>
95  
96 <li>You're ready to roll! <a href="#managing">More info on how to roll...</a></li>
97 </ol>
98  
99 <p>Optional but recommended:</p>
100 <ul>
101 <li>Have a browse through <code>singapore.ini</code> and look at the
102 available options. Each option has comments explaining its function. For most
103 purposes the default values will be fine but you may be able to tweak them
104 to your benefit. See also <a href="Advanced.html#override">overriding default
105 settings</a>.</li>
106  
107 <li>Make your own header image (<code>templates/default/images/header.gif</code>)
108 with the name of your site.<br />
109 -or-<br />
110 Edit the default style sheet (<code>templates/default/main.css</code>)
111 to integrate it with your site.<br />
112 -or-<br />
113 Browse the pre-existing templates available for singapore on the
114 <a href="http://www.sgal.org/wiki/files/templates">templates</a> page.
115 -or-<br />
116 Create your own template by editing an existing one. There is currently no
117 documentation on this topic but anyone with a basic grasp of PHP should be
118 able to work it out. Visit the
119 <a href="http://www.sgal.org/forum/viewforum.php?id=2">templates forum</a>
120 for help and advice.</li>
121 </ul>
122  
123  
124 <h2><a name="upgrade">Upgrading</a></h2>
125  
126 <p>Always back-up first!</p>
127  
128 <p>A patch is also available for people wishing only to fix the security problem.</p>
129  
130 <p>Upgrading is usually just a matter of unzipping the new version over the old.
131 Your galleries, images, metadata will not be affected but the
132 admin password will be reset and the root ini file (singapore.ini) will be
133 overwritten. The location of log files and thumbnail cache has changed in this
134 version. See the forum for
135 <a href="http://www.sgal.org/forum/viewtopic.php?id=1267">instructions on
136 copying your old logs over to their new location</a>.
137 You can keep your old users.csv.php file.
138 When new configuration options are added you will need to either add these
139 to your old singapore.ini or re-edit the new singapore.ini in order to keep your
140 personal settings. You may want to use a file difference utility such as
141 <a href="http://winmerge.sourceforge.net">WinMerge</a> to merge the differences.</p>
142  
143 <p>The default templates will also be overwritten in an upgrade. For this reason
144 it is advisable to copy the default template to a new directory when making
145 customisations.</p>
146  
147  
148 <h2><a name="uninstall">Uninstallation</a></h2>
149  
150 <p>Server generated content may be owned by the web server and it may therefore
151 not be possible to delete these files via ftp. Use the
152 <a href="../tools/cleanup.php">cleanup script</a> to make all server-generated
153 files world writable. This should allow you to delete them like any other file.</p>
154  
155  
156 <h2><a name="managing">Managing your galleries</a></h2>
157  
158 <p>If using the <a href="Advanced.html#iifn">info in file name</a> system then
159 all management can be done
160 directly on the files using, for example, an ftp client. To create new galleries
161 simply create a new subdirectory of <code>galleries/</code>. To add, move or delete
162 images in a gallery simply add, move or delete the image files in the
163 appropriate directory.</p>
164  
165 <p>If you use the admin mode to edit your galleries or images it will
166 automatically create the relevant metadata files. If these files are deleted
167 singapore will revert to using <em>info in file name</em>. The username is
168 <code>admin</code> and the default password is <code>password</code>.</p>
169  
170 <p>Galleries may contain <em>either</em> images or further galleries. This
171 means that if you create one or more child galleries in a gallery that already
172 contains images, these images will be 'hidden'. Removing these child galleries
173 will make the images visible again. Galleries containing only images are called
174 albums.</p>
175  
176  
177 <h3>Bulk image uploading</h3>
178  
179 <p class="note">NOTE: this feature is experimental. It works on some servers but
180 does not on others (including the sf.net servers) and I don't know why. It may
181 or may not work for you.</p>
182  
183 <p>You may upload several images at the same time by first storing them in a
184 PKWARE compatible ZIP file. Most archiving utilities are able to produce such
185 files also sometimes referred to as <em>compressed folders</em> on Windows. You
186 need an unzipping utility on your server to use this feature. Most Linux/Unix
187 machines come with the free <em>unzip</em> utility by Info-Zip preinstalled but
188 precompiled binaries for nearly all operating systems ever conceived can be
189 found on the <a href="http://www.info-zip.org/">Info-Zip website</a>. <!--A Win32
190 version is also available here:
191 <a href="http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip</a>.-->
192 Simply place the executable in your PATH or in the singapore root directory.</p>
193  
194 <p>Upload the archive using the 'new image' option in the singapore admin and
195 select 'Upload multiple files'</p>
196  
197 <p>If the archive contains only images, these will be added to the current
198 gallery just as if they had been uploaded individually. If an archive contains
199 subdirectories, these will be copied into the current gallery. Any images in
200 the archive root directory will be imported as above. This mechanism
201 may be used to upload complete directory structures including metadata.csv
202 and gallery.ini files. If the archive root directory contains no images and a
203 single directory, singapore will navigate into this directory and proceed to
204 import the contents into the current gallery as though they were in the root
205 directory.</p>
206  
207 <p>NOTE: There is a maximum size of file that PHP will allow you to upload.
208 This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual
209 or you server's administrator for more information.</p>
210  
211 <h2><a name="permissions">Help with file permissions</a></h2>
212  
213 <p>How to make a file writable is dependent on your operating system and
214 web server setup and can seem quite daunting for a beginner. One option that
215 will work on nearly all Unix/Linux servers is to chmod the relevant
216 files/directories to 777 (consult your FTP software documentation for help on
217 using the chmod command). However this option is not considered very secure as
218 anyone who has write access the web server (such as the owners of other web
219 sites hosted on the same computer) can potentially write to or delete these
220 directories. There may be a better way to make your files writable by your
221 server but this is something you must take up with your server administrator.</p>
222  
223  
224 <h2><a name="adminpermissions">The deal with admin permissions</a></h2>
225  
226 <p>First thing to point out is that singapore admin permissions are not related
227 to unix/windows filesystem permissions. If you get a "permission denied" message
228 from php about a certain file, that's the filesystem permissions discussed in a
229 <a href="#permissions">separate section</a>. For the purposes of this section an
230 'object' is anything that can have admin permissions associated with it; i.e. an
231 image or a gallery.</p>
232  
233 <p>There are two types of users: administrators and users. Administrators can do
234 everything and are not bound by permission settings. Only administrators may
235 create and edit users and change ownership of objects. Ownership is set at the
236 time of creation of the object to the user creating the object. The owner of an
237 object may do anything to it except change the owner. Only the owner or an
238 administrator may alter the permissions of an object, including changing its
239 group(s).</p>
240  
241 <p>There are four kinds of action that may be either allowed or disallowed:
242 read, edit, add and delete. Read permissions allow an object to be viewed. Edit
243 permissions allow a user to edit (i.e. change) aspects of the object. Add
244 permissions allow a user to add sub objects (i.e. images and subgalleries). This
245 is obviously meaningless when applied to images but it may be used later to
246 allow image comments. Finally Delete permissions allow a user to delete the
247 object concerned (and any sub objects).</p>
248  
249 <p>These four permissions come in two flavours: group and world. World
250 permissions apply to all users so if, for example, a gallery has the world add
251 permission set then any user can add objects to it. The groups system is
252 slightly less intuitive but very powerful. A user may belong to any number of
253 groups. These groups are simply alphanumeric names separated by spaces. An
254 object may also belong to any number of groups. If a user belongs to at least
255 one group to which the object concerned also belongs then the group permissions
256 are considered. For example a user has this for their groups field "team23
257 photographers friends" and an image belongs to the following groups "friends
258 family" and has the group delete permission set then that user may delete the
259 object since both belong to the group 'friends'.</p>
260  
261 <p>Permissions are NOT inherited from parent objects.</p>
262  
263 <p class="note">NOTE: read permissions are not currently enforced, a future
264 version will prevent anyone from seeing objects that do not have sufficient read
265 permissions. Note also that there is no mechanism to set image permissions this
266 will be amended in a later release. Finally, since there is no database
267 concurrency handling, odd things might happen if two users are making changes
268 to the same gallery or image simultaneously.</p>
269  
270  
271 <h2><a name="users">Managing users</a></h2>
272  
273 <p>As mentioned above there are two types of users: administrators and users.
274 Administrators can do everything and are not bound by permission settings. Only
275 administrators may create and edit users. Administrators may also edit existing
276 users' details including changing their passwords though, of course, they cannot
277 view their existing passwords.</p>
278  
279 <p>Users may also be suspended. This preserves all the user's details but
280 prevents them from loggin in until their account is unsuspended by an
281 administrator.</p>
282  
283 <p>There are two built-in accounts that cannot be deleted. The "admin" account
284 is an administrator. The "guest" account is special. It is like a user account
285 except that guests have no password, cannot change their details and cannot own
286 objects. This means guests can only affect objects with the appropriate world
287 permissions set. Any object created by a guest is owned by the special user
288 "__nobody__" and has full read, edit, add and delete permissions for both world
289 and group. You may disable guest access to your gallery by suspending the guest
290 user.</p>
291  
292  
293 <h2><a name="nomenclature">Naming of parts</a></h2>
294  
295 <dl>
296  
297 <dt>Installation</dt>
298 <dd>an installation of singapore is contained within a website. It is usually
299 in its own separate directory and contains one gallery: the root gallery.</dd>
300  
301 <dt>Root gallery</dt>
302 <dd>There is only one root gallery and it is not contained within any other
303 galleries. It is located directly in the directory specified by the
304 <code>pathto_galleries</code> option. It is usually referred to in URLs with a
305 single dot (as in <code>?gallery=.</code>).</dd>
306  
307 <dt>Gallery</dt>
308 <dd>a gallery is contained within another gallery (except the root gallery
309 which is contained in an installation). Galleries may contain more galleries
310 and also images.</dd>
311  
312 <dt>Album</dt>
313 <dd>an album is a special case of gallery that contains exactly zero
314 galleries and zero or more images. In other words a gallery is called an
315 album when it does not have any child galleries. So an album is a gallery
316 but a gallery is not an album in much the same way that a kitchen is a room
317 but a room is not a kitchen.</dd>
318  
319 <dt>Image</dt>
320 <dd>an image is contained within an album or a gallery. Due to the way
321 singapore operates, images will only be displayed if they are in albums since
322 any images in non-album galleries will be hidden.</dd>
323  
324 <dt>Child gallery (also known as subgallery)</dt>
325 <dd>this is a relative term. A child gallery is one contained within the
326 gallery currently being viewed or edited. There may be zero or more.</dd>
327  
328 <dt>Parent gallery</dt>
329 <dd>this is a relative term. The parent gallery is the one which contains the
330 gallery currently being viewed or edited. There is always exactly one (except
331 in the case of the root gallery which has no parent).</dd>
332  
333 </dl>
334  
335 <h2><a name="history">Version history</a></h2>
336  
337 <pre>Key to symbols:
338 + added
339 - removed
340 * fixed
341 o changed
342 </pre>
343  
344 <p>A complete and up-to-date CVS changelog is
345 <a href="http://www.sgal.org/cvsdemo/ChangeLog">available online</a>.</p>
346  
347 <h3>0.10.1 - 2006-09-20</h3>
348  
349 <pre>
350 * fixed template security issue
351 + access control settings are inherited by child galleries
352 * fixed image hits total
353 o updated modern template (see separate changelog)
354 </pre>
355  
356 <h3>0.10.0 - 2006-05-17</h3>
357  
358 <pre>
359 o code is now more object oriented and easier to understand
360 + added safe_mode hack using FTP
361 + can move &amp; copy galleries in admin
362 + can batch delete images and galleries in admin
363 o thumbnails and logs stored in each gallery
364 + thumbnails created on page load and statically linked
365 + ancestor metadata is parsed for crumb line
366 o removed leading ./ from gallery id in urls
367 + next and previous gallery links
368 + 'up' links to correct page of parent gallery
369 * base_path and base_url are no longer overwritten by external.php
370 * fixed eastern european characters in data fields
371 * fixed new lines in summary field
372 * fixed image resizing bug when image size equals maxsize
373 * fixed imagemagick v6.x support
374 * fixed session.auto_start bug (aka login loop)
375 * fixed XSS vulnerability in template &amp; language flippers
376 + added sort by date field to galleries
377 o rewritten hit logging code
378 o added explicit chmod's instead of relying on umask
379 o new admin error handling in preparetion for our new admin backend
380 </pre>
381  
382 <h3>0.9.11 - 2004-12-15</h3>
383  
384 <pre>
385 + added SQL abstraction backend with support for MySQL and SQLite
386 o changed IO class hierarchy
387 o streamlined install process
388 + separated editprofile from edituser
389 * fixed multiple vulnerabilities (thanks to SIG^2)
390 + added allow_dir_upload config option
391 </pre>
392  
393 <h3>0.9.10 - 2004-10-20</h3>
394  
395 <pre>
396 + implemented full multi-user support with permissions
397 + reindex metadata feature in admin for importing ftp'd images
398 + language and template are now user-selectable on-the-fly
399 + language may be auto-detected from user agent headers
400 + summary field now used instead of description field
401 o introduced new streamlined admin template with quicklinks
402 o tidied up css classes and annotated the default stylesheet
403 * fixed md5 dictionary attack vulnerability by hiding user account details
404 * fixed security issue with back-references in arguments to thumb.php
405 o made thumb.php reject files with extensions not in recognised_extensions
406 o changed base_file config option to index_file_url
407 o changed language config option to default_language
408 o changed template_name config option to default_template
409 + new external.php file for integrating singapore into existing layouts
410 </pre>
411  
412 <h3>0.9.9b - 2004-08-08</h3>
413  
414 <pre>
415 * fixed image size calculation (again)
416 </pre>
417  
418 <h3>0.9.9a - 2004-06-11</h3>
419  
420 <pre>
421 * fixed multi-page galleries bug in templates
422 * fixed XHTML compliance
423 * fixed image size calculation
424 * possibly other things
425 </pre>
426  
427 <h3>0.9.9 - 2004-05-15</h3>
428  
429 <pre>
430 + added multi-image upload using ZIP files
431 + added fixed size and aspect ratio thumbnail creation
432 * fixed umask functionality (thanks to afuhrmann)
433 + added navigation by clickable image map
434 + added upload_overwrite config option
435 o moved url generation into separate function(s) (acsissman)
436 + enabled use of mod_rewrite with appropriate .htaccess (acsissman)
437 + added progressive jpeg option (thanks to joeforker)
438 o moved i18n functions into separate class
439 * made site navigation links xhtml compatible
440 * fixed special characters in filenames under ImageMagick *again*?
441 o introduced consistent 'gallery>album>image' naming scheme
442 o GD2 used as default thumbnail_software (GD1 support unaffected)
443 </pre>
444  
445 <h3>0.9.8 - 2004-01-06</h3>
446  
447 <pre>
448 + automatic recognition of most URLs in 'description' field
449 + do not process directories starting with dot (.)
450 + enabled navigation bar in supporting browsers (e.g. mozilla, opera)
451 o made 'artist - name' iifn parsing optional
452 * fixed bizarre sort order in admin mode
453 * use htmlspecialchars instead of htmlentities
454 * fixed using special chars in filenames when magic_quotes_gpc is on (again)
455 * fixed code that produced 'Notice' level errors with PHP 5
456 </pre>
457  
458 <h3>0.9.7 - 2003-11-17</h3>
459  
460 <pre>
461 + added forced image resizing to fixed size
462 + added rudimentary image and gallery sort ordering
463 * fixed multi-page galleries listings
464 * fixed zero-width thumbnails for failed uploads
465 + added a few functions useful for templates
466 + added .jpe extension
467 o changed details array format
468 + added basePath parameter to allow removed instantiation of singapore class
469 o fixed some untranslated strings in admin mode
470 * maybe fixed using special chars in filenames when magic_quotes_gpc is on
471 + added back-reference check to prevent file-system walking
472 o merged __g functionality into _g and _ng
473 </pre>
474  
475 <h3>0.9.6 - 2003-08-15</h3>
476  
477 <pre>
478 o code entirely reorganised and largely re-written into classes
479 + multilanguage (i18n) support
480 o interface is template driven
481 + per-gallery and per-template configuration files
482 + nested gallery support (unlimited depth)
483 + crumb line for easier navigation
484 * all image and gallery names are now urlencoded
485 + many new config options
486 </pre>
487  
488 <h3>0.9.5 - 2003-05-31</h3>
489  
490 <pre>
491 * fixed GD2 support in thumb.php (0.9.4a always used GD1)
492 - removed secret string option
493 + added config options for admin session name (allows multiple installs on same server),
494 path to convert (ImageMagick), remove jpeg profile (ImageMagick),
495 character encoding &amp; site name (page title)
496 o execution_timer off by default and default galleries per page set to 10
497 + thumb.php always uses fopen on remote files (now works on windows)
498 + more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir)
499 </pre>
500  
501 <h3>0.9.4a - 2003-05-16</h3>
502  
503 <pre>
504 + added PNG and GIF support under GD (GIF only with compatible versions of GD)
505 + added PNG, GIF, TIFF, BMP, and support from pretty much every
506 other file type under ImageMagick
507 + more checks in test.php
508 * fixed image counting in iifn mode
509 * fixed show_image_name_in_thumbnail_view
510 + images link back to correct page of gallery (second link)
511 </pre>
512  
513 <h3>0.9.4 - 2003-05-13</h3>
514  
515 <pre>
516 o changed config to ini file + global config object
517 o changed directory structure (moved documentation into docs/, moved writable files into data/)
518 + gallery (thumbnail) view shows more information
519 + gallery (thumbnail) view can show image name under thumbnail (off by default)
520 + gallery (list) view shows number of images in gallery
521 + implemented random thumbnail image in gallery (list) view
522 + added test.php and setup.php (not very useful yet)
523 * fixed handling of gallery_thumb_number config option
524 * password change bug
525 * remote file thumbnail generation with ImageMagick
526 </pre>
527  
528 <h3>0.9.3 - 2003-05-10</h3>
529  
530 <pre>
531 + web admin can add and delete images and galleries
532 + added GD 2 and ImageMagic thumbnail generation support
533 * does not generate any E_NOTICE errors anymore
534 + added config option for generated thumbnail JPEG quality
535 * handles extended characters in gallery and image names (Piotr)
536 * fixed 'images link back to correct page of gallery'
537 + added directory_mode and file_mode options
538 * track_views and show_views now work independently
539 o admin bar now visible everywhere when logged in
540 </pre>
541  
542 <h3>0.9.2 - 2003-04-27</h3>
543  
544 <pre>
545 * fixed non-expiration of admin sessions in some cases
546 + added purge cached thumbnails option
547 + new 'XP' theme
548 * fixed hit logging functions
549 + added image hit log viewing in admin mode
550 + images link back to correct page of gallery
551 o optimised config.php
552 * fixed some css issues
553 </pre>
554  
555 <h3>0.9.1 - 2003-04-23</h3>
556  
557 <pre>
558 o changed database format
559 + added visible database fields for artist email, darkroom manipulation and
560 digital manipulation
561 + added invisible (control) database fields for thumbnail, owner, groups and categories
562 o put header and footer code into separate files
563 + implemented limited themeing support
564 + added config options for custom paths to cache, galleries, logs, themes,
565 header, footer and custom css
566 o improved navigation in admin mode
567 + added optional script execution timer
568 * fixed proliferation of newlines in 'desc' field
569 * fixed wrongly escaped characters when saving info
570 </pre>
571  
572 <h3>0.9a - 2003-04-13</h3>
573  
574 <pre>
575 + added much better documentation
576 </pre>
577  
578 <h3>0.9 - 2003-03-30</h3>
579  
580 <pre>
581 + admin section (allows editing image and gallery info)
582 + nicer gallery list layout
583 + filename parser for if no metadata file found
584 o split into separate include files for io operations, ui generation etc
585 * fixed some css issues
586 + lots of other little things
587 </pre>
588  
589 <h3>0.0 (unnumbered version) - 2003-03-29</h3>
590  
591 <pre>
592 o first release under GPL
593 + everything
594 </pre>
595  
596 <p><em>$Date: 2006/05/18 16:14:20 $</em></p>
597  
598 </body>
599 </html>