# singapore v0.10.1 - Readme

- Release notes
- Version history
- License information
- Installation
- Upgrading
- Gallery management
- Help with file permissions
- The deal with admin permissions
- Managing users
- Naming of parts (glossary)
- Advanced features
- Developer documentation
- Translating singapore

## Licensing information

     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
     *  singapore - Copyright 2002-6 Tamlyn Rhodes <tam@zenology.co.uk>    *
     *                                                                     *
     *  singapore is free software; you can redistribute it and/or modify  *
     *  it under the terms of the GNU General Public License as published  *
     *  by the Free Software Foundation; either version 2 of the License,  *
     *  or (at your option) any later version.                             *
     *                                                                     *
     *  singapore is distributed in the hope that it will be useful,       *
     *  but WITHOUT ANY WARRANTY; without even the implied warranty        *
     *  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.            *
     *  See the GNU General Public License for more details.               *
     *                                                                     *
     *  You should have received a copy of the GNU General Public License  *
     *  along with this; if not, write to the Free Software Foundation,    *
     *  Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA      *
     \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

You are kindly requested to display a link such as the following on all pages generated by singapore. However in cases where this is not desirable, a project donation of 20USD is considered a suitable alternative.

Powered by singapore

## Release notes

This is a recommended update as it addresses a critical bug in the template handling that could allow an attacker to view the contents of system files on the web server. Several other less severe bugs have been fixed including acces control settings inheritance in the admin which should now work correctly. The latest version of the 'modern' template is also included.

## Installation

1. Extract all the files in the archive, conserving the directory hierarchy.
2. If you wish to change any path settings or use one of the SQL backends, make the necessary changes to `singapore.ini`. If you don't know why you might want to do this then you don't need to do it.
3. Upload everything to your web server.
4. Set file permissions. The directories that need to be made writable are:
   - `data/` and all subdirectories and files
   - `galleries/` and all subdirectories and files
   Help with file permissions.
5. Point your browser to the `install/` directory and follow the instructions.
6. Delete the `install/` directory to prevent unauthorised access.
7. Log into the admin section and change the password. The username is `admin` and the default password is `password`.
8. You're ready to roll! More info on how to roll...

Optional but recommended:

- Have a browse through `singapore.ini` and look at the available options. Each option has comments explaining its function. For most purposes the default values will be fine but you may be able to tweak them to your benefit. See also overriding default settings.
- Make your own header image (`templates/default/images/header.gif`) with the name of your site.
  -or-
  Edit the default style sheet (`templates/default/main.css`) to integrate it with your site.
  -or-
  Browse the pre-existing templates available for singapore on the templates page. -or-
  Create your own template by editing an existing one. There is currently no documentation on this topic but anyone with a basic grasp of PHP should be able to work it out. Visit the templates forum for help and advice.

## Upgrading

Always back-up first!

A patch is also available for people wishing only to fix the security problem.

Upgrading is usually just a matter of unzipping the new version over the old. Your galleries, images, metadata will not be affected but the admin password will be reset and the root ini file (singapore.ini) will be overwritten. The location of log files and thumbnail cache has changed in this version. See the forum for instructions on copying your old logs over to their new location. You can keep your old users.csv.php file. When new configuration options are added you will need to either add these to your old singapore.ini or re-edit the new singapore.ini in order to keep your personal settings. You may want to use a file difference utility such as WinMerge to merge the differences.

The default templates will also be overwritten in an upgrade. For this reason it is advisable to copy the default template to a new directory when making customisations.

## Uninstallation

Server generated content may be owned by the web server and it may therefore not be possible to delete these files via ftp. Use the cleanup script to make all server-generated files world writable. This should allow you to delete them like any other file.

## Managing your galleries

If using the info in file name system then all management can be done directly on the files using, for example, an ftp client. To create new galleries simply create a new subdirectory of `galleries/`. To add, move or delete images in a gallery simply add, move or delete the image files in the appropriate directory.

If you use the admin mode to edit your galleries or images it will automatically create the relevant metadata files. If these files are deleted singapore will revert to using info in file name. The username is `admin` and the default password is `password`.

Galleries may contain either images or further galleries. This means that if you create one or more child galleries in a gallery that already contains images, these images will be 'hidden'. Removing these child galleries will make the images visible again. Galleries containing only images are called albums.

### Bulk image uploading

NOTE: this feature is experimental. It works on some servers but does not on others (including the sf.net servers) and I don't know why. It may or may not work for you.

You may upload several images at the same time by first storing them in a PKWARE compatible ZIP file. Most archiving utilities are able to produce such files also sometimes referred to as compressed folders on Windows. You need an unzipping utility on your server to use this feature. Most Linux/Unix machines come with the free unzip utility by Info-Zip preinstalled but precompiled binaries for nearly all operating systems ever conceived can be found on the Info-Zip website. Simply place the executable in your PATH or in the singapore root directory.

Upload the archive using the 'new image' option in the singapore admin and select 'Upload multiple files'

If the archive contains only images, these will be added to the current gallery just as if they had been uploaded individually. If an archive contains subdirectories, these will be copied into the current gallery. Any images in the archive root directory will be imported as above. This mechanism may be used to upload complete directory structures including metadata.csv and gallery.ini files. If the archive root directory contains no images and a single directory, singapore will navigate into this directory and proceed to import the contents into the current gallery as though they were in the root directory.

NOTE: There is a maximum size of file that PHP will allow you to upload. This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual or you server's administrator for more information.

## Help with file permissions

How to make a file writable is dependent on your operating system and web server setup and can seem quite daunting for a beginner. One option that will work on nearly all Unix/Linux servers is to chmod the relevant files/directories to 777 (consult your FTP software documentation for help on using the chmod command). However this option is not considered very secure as anyone who has write access the web server (such as the owners of other web sites hosted on the same computer) can potentially write to or delete these directories. There may be a better way to make your files writable by your server but this is something you must take up with your server administrator.

## The deal with admin permissions

First thing to point out is that singapore admin permissions are not related to unix/windows filesystem permissions. If you get a "permission denied" message from php about a certain file, that's the filesystem permissions discussed in a separate section. For the purposes of this section an 'object' is anything that can have admin permissions associated with it; i.e. an image or a gallery.

There are two types of users: administrators and users. Administrators can do everything and are not bound by permission settings. Only administrators may create and edit users and change ownership of objects. Ownership is set at the time of creation of the object to the user creating the object. The owner of an object may do anything to it except change the owner. Only the owner or an administrator may alter the permissions of an object, including changing its group(s).

There are four kinds of action that may be either allowed or disallowed: read, edit, add and delete. Read permissions allow an object to be viewed. Edit permissions allow a user to edit (i.e. change) aspects of the object. Add permissions allow a user to add sub objects (i.e. images and subgalleries). This is obviously meaningless when applied to images but it may be used later to allow image comments. Finally Delete permissions allow a user to delete the object concerned (and any sub objects).

These four permissions come in two flavours: group and world. World permissions apply to all users so if, for example, a gallery has the world add permission set then any user can add objects to it. The groups system is slightly less intuitive but very powerful. A user may belong to any number of groups. These groups are simply alphanumeric names separated by spaces. An object may also belong to any number of groups. If a user belongs to at least one group to which the object concerned also belongs then the group permissions are considered. For example a user has this for their groups field "team23 photographers friends" and an image belongs to the following groups "friends family" and has the group delete permission set then that user may delete the object since both belong to the group 'friends'.

Permissions are NOT inherited from parent objects.

NOTE: read permissions are not currently enforced, a future version will prevent anyone from seeing objects that do not have sufficient read permissions. Note also that there is no mechanism to set image permissions this will be amended in a later release. Finally, since there is no database concurrency handling, odd things might happen if two users are making changes to the same gallery or image simultaneously.

## Managing users

As mentioned above there are two types of users: administrators and users. Administrators can do everything and are not bound by permission settings. Only administrators may create and edit users. Administrators may also edit existing users' details including changing their passwords though, of course, they cannot view their existing passwords.

Users may also be suspended. This preserves all the user's details but prevents them from loggin in until their account is unsuspended by an administrator.

There are two built-in accounts that cannot be deleted. The "admin" account is an administrator. The "guest" account is special. It is like a user account except that guests have no password, cannot change their details and cannot own objects. This means guests can only affect objects with the appropriate world permissions set. Any object created by a guest is owned by the special user "__nobody__" and has full read, edit, add and delete permissions for both world and group. You may disable guest access to your gallery by suspending the guest user.

## Naming of parts

Installation
  an installation of singapore is contained within a website. It is usually in its own separate directory and contains one gallery: the root gallery.
Root gallery
  There is only one root gallery and it is not contained within any other galleries. It is located directly in the directory specified by the `pathto_galleries` option. It is usually referred to in URLs with a single dot (as in `?gallery=.`).
Gallery
  a gallery is contained within another gallery (except the root gallery which is contained in an installation). Galleries may contain more galleries and also images.
Album
  an album is a special case of gallery that contains exactly zero galleries and zero or more images. In other words a gallery is called an album when it does not have any child galleries. So an album is a gallery but a gallery is not an album in much the same way that a kitchen is a room but a room is not a kitchen.
Image
  an image is contained within an album or a gallery. Due to the way singapore operates, images will only be displayed if they are in albums since any images in non-album galleries will be hidden.
Child gallery (also known as subgallery)
  this is a relative term. A child gallery is one contained within the gallery currently being viewed or edited. There may be zero or more.
Parent gallery
  this is a relative term. The parent gallery is the one which contains the gallery currently being viewed or edited. There is always exactly one (except in the case of the root gallery which has no parent).

## Version history

    Key to symbols:
    + added
    - removed
    * fixed
    o changed

A complete and up-to-date CVS changelog is available online.

### 0.10.1 - 2006-09-20

    * fixed template security issue
    + access control settings are inherited by child galleries
    * fixed image hits total
    o updated modern template (see separate changelog)

### 0.10.0 - 2006-05-17

    o code is now more object oriented and easier to understand
    + added safe_mode hack using FTP
    + can move & copy galleries in admin
    + can batch delete images and galleries in admin
    o thumbnails and logs stored in each gallery
    + thumbnails created on page load and statically linked
    + ancestor metadata is parsed for crumb line
    o removed leading ./ from gallery id in urls
    + next and previous gallery links
    + 'up' links to correct page of parent gallery
    * base_path and base_url are no longer overwritten by external.php
    * fixed eastern european characters in data fields
    * fixed new lines in summary field
    * fixed image resizing bug when image size equals maxsize
    * fixed imagemagick v6.x support
    * fixed session.auto_start bug (aka login loop)
    * fixed XSS vulnerability in template & language flippers
    + added sort by date field to galleries
    o rewritten hit logging code
    o added explicit chmod's instead of relying on umask
    o new admin error handling in preparetion for our new admin backend

### 0.9.11 - 2004-12-15

    + added SQL abstraction backend with support for MySQL and SQLite
    o changed IO class hierarchy
    o streamlined install process
    + separated editprofile from edituser
    * fixed multiple vulnerabilities (thanks to SIG^2)
    + added allow_dir_upload config option

### 0.9.10 - 2004-10-20

    + implemented full multi-user support with permissions
    + reindex metadata feature in admin for importing ftp'd images
    + language and template are now user-selectable on-the-fly
    + language may be auto-detected from user agent headers
    + summary field now used instead of description field
    o introduced new streamlined admin template with quicklinks
    o tidied up css classes and annotated the default stylesheet
    * fixed md5 dictionary attack vulnerability by hiding user account details
    * fixed security issue with back-references in arguments to thumb.php
    o made thumb.php reject files with extensions not in recognised_extensions
    o changed base_file config option to index_file_url
    o changed language config option to default_language
    o changed template_name config option to default_template
    + new external.php file for integrating singapore into existing layouts

### 0.9.9b - 2004-08-08

    * fixed image size calculation (again)

### 0.9.9a - 2004-06-11

    * fixed multi-page galleries bug in templates
    * fixed XHTML compliance
    * fixed image size calculation
    * possibly other things

### 0.9.9 - 2004-05-15

    + added multi-image upload using ZIP files
    + added fixed size and aspect ratio thumbnail creation
    * fixed umask functionality (thanks to afuhrmann)
    + added navigation by clickable image map
    + added upload_overwrite config option
    o moved url generation into separate function(s) (acsissman)
    + enabled use of mod_rewrite with appropriate .htaccess (acsissman)
    + added progressive jpeg option (thanks to joeforker)
    o moved i18n functions into separate class
    * made site navigation links xhtml compatible
    * fixed special characters in filenames under ImageMagick *again*?
    o introduced consistent 'gallery>album>image' naming scheme
    o GD2 used as default thumbnail_software (GD1 support unaffected)

### 0.9.8 - 2004-01-06

    + automatic recognition of most URLs in 'description' field
    + do not process directories starting with dot (.)
    + enabled navigation bar in supporting browsers (e.g. mozilla, opera)
    o made 'artist - name' iifn parsing optional
    * fixed bizarre sort order in admin mode
    * use htmlspecialchars instead of htmlentities
    * fixed using special chars in filenames when magic_quotes_gpc is on (again)
    * fixed code that produced 'Notice' level errors with PHP 5

### 0.9.7 - 2003-11-17

    + added forced image resizing to fixed size
    + added rudimentary image and gallery sort ordering
    * fixed multi-page galleries listings
    * fixed zero-width thumbnails for failed uploads
    + added a few functions useful for templates
    + added .jpe extension
    o changed details array format
    + added basePath parameter to allow removed instantiation of singapore class
    o fixed some untranslated strings in admin mode
    * maybe fixed using special chars in filenames when magic_quotes_gpc is on
    + added back-reference check to prevent file-system walking
    o merged __g functionality into _g and _ng

### 0.9.6 - 2003-08-15

    o code entirely reorganised and largely re-written into classes
    + multilanguage (i18n) support
    o interface is template driven
    + per-gallery and per-template configuration files
    + nested gallery support (unlimited depth)
    + crumb line for easier navigation
    * all image and gallery names are now urlencoded
    + many new config options

### 0.9.5 - 2003-05-31

    * fixed GD2 support in thumb.php (0.9.4a always used GD1)
    - removed secret string option
    + added config options for admin session name (allows multiple installs on same server),
      path to convert (ImageMagick), remove jpeg profile (ImageMagick),
      character encoding & site name (page title)
    o execution_timer off by default and default galleries per page set to 10
    + thumb.php always uses fopen on remote files (now works on windows)
    + more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir)

### 0.9.4a - 2003-05-16

    + added PNG and GIF support under GD (GIF only with compatible versions of GD)
    + added PNG, GIF, TIFF, BMP, and support from pretty much every
      other file type under ImageMagick
    + more checks in test.php
    * fixed image counting in iifn mode
    * fixed show_image_name_in_thumbnail_view
    + images link back to correct page of gallery (second link)

### 0.9.4 - 2003-05-13

    o changed config to ini file + global config object
    o changed directory structure (moved documentation into docs/, moved writable files into data/)
    + gallery (thumbnail) view shows more information
    + gallery (thumbnail) view can show image name under thumbnail (off by default)
    + gallery (list) view shows number of images in gallery
    + implemented random thumbnail image in gallery (list) view
    + added test.php and setup.php (not very useful yet)
    * fixed handling of gallery_thumb_number config option
    * password change bug
    * remote file thumbnail generation with ImageMagick

### 0.9.3 - 2003-05-10

    + web admin can add and delete images and galleries
    + added GD 2 and ImageMagic thumbnail generation support
    * does not generate any E_NOTICE errors anymore
    + added config option for generated thumbnail JPEG quality
    * handles extended characters in gallery and image names (Piotr)
    * fixed 'images link back to correct page of gallery'
    + added directory_mode and file_mode options
    * track_views and show_views now work independently
    o admin bar now visible everywhere when logged in

### 0.9.2 - 2003-04-27

    * fixed non-expiration of admin sessions in some cases
    + added purge cached thumbnails option
    + new 'XP' theme
    * fixed hit logging functions
    + added image hit log viewing in admin mode
    + images link back to correct page of gallery
    o optimised config.php
    * fixed some css issues

### 0.9.1 - 2003-04-23

    o changed database format
    + added visible database fields for artist email, darkroom manipulation and
      digital manipulation
    + added invisible (control) database fields for thumbnail, owner, groups and categories
    o put header and footer code into separate files
    + implemented limited themeing support
    + added config options for custom paths to cache, galleries, logs, themes,
      header, footer and custom css
    o improved navigation in admin mode
    + added optional script execution timer
    * fixed proliferation of newlines in 'desc' field
    * fixed wrongly escaped characters when saving info

### 0.9a - 2003-04-13

    + added much better documentation

### 0.9 - 2003-03-30

    + admin section (allows editing image and gallery info)
    + nicer gallery list layout
    + filename parser for if no metadata file found
    o split into separate include files for io operations, ui generation etc
    * fixed some css issues
    + lots of other little things

### 0.0 (unnumbered version) - 2003-03-29

    o first release under GPL
    + everything

$Date: 2006/05/18 16:14:20 $