Ochiba documentation

Ochiba is a web-based image gallery written in PHP. It's a hybrid of traditional "photo album" software, such as Gallery or Coppermine, and "image board" software, such as futaba, futallaby, and wakaba. In addition, it borrows concepts found in sources such as gmail and iPhoto to provide a flexible, keyword/tag based filtering of displayed images which can be used to create on-the-fly "virtual" albums.

Other features include: XHTML/CSS complicance, RSS feeds for image categories, post throttling, IP banning, caching, visual image-based post verification (CAPTCHA) for spam-prevention, and zip file handling (for multiple images in one upload).

Table of Contents

Requirements

At the bare minimum, you will need:

  • Apache, with mod_rewrite, and the following overrides for the directory: Options Indexes FileInfo. Please see the included .htaccess file for specifics.
  • PHP >=4.3 with database support (sqlite, PostgreSQL, MySQL supported via PEAR::DB - other databases may work)
  • PEAR::DB
  • PEAR::HTML_Template_IT
  • ImageMagick (convert and identify)
  • On the client side, a relatively current browser (Gecko-based browsers, Safari, or IE6) with Javascript processing and cookie acceptance is required.

Please see the requirements help page for additional information about obtaining PEAR::DB or PEAR::HTML_Template_IT for your system.

The following are considered "optional", but without them, you will not be able to use some of the functionality or have to put up with some inconvenience.

  • wget or curl (for remote image fetches). Without one of these, remote image fetches will not be available.
  • file and unzip (for zip file handling). Without these, the ability to upload a zip file of images will not work.

Quick Start

  • Untar ochiba somewhere. You can rename the directory from ochiba to something else.
  • Make img/, and thumbs/ writable by the web process. You'll also need to create a cache dir at /tmp/ochiba-cache (the default location) also writable by the web process.
  • Edit conf.php:
    • Specify the PEAR::DB database source name (DSN). This is defined as DB, and examples for various supported databases are included. If you are using sqlite, the sqlite database file and the directory that contains it must be writable by the web process. It would be a bad idea to have this database within the web document root.
    • Change the TRIPCODE_SECRET parameter from "changeme" to something else.
    • Change the FEATURE_RESTRICT_POSTING parameter to "ADMINS" if you are going to be using ochiba in "photo album" mode (only certain users can post). See below for details.
  • Go to http://your.site/path/to/ochiba/install.php. This will attempt to create your database, and will make some checks. Hopefully it will go well.
  • Go to http://your.site/path/to/ochiba/admin. You'll see some error messages- ignore them. Enter a tripcode. Copy the new tripcode when it is generated into conf.php, parameter ADMINS
  • Go back to http://your.site/path/to/ochiba/admin. Create a category.
  • You're set to go!

Installation Details

The following provides more detailed instructions on getting ochiba installed. It assumes you have shell access, which will make the installation a lot simpler. If you don't have shell access, then you will have to do a lot of uploading, but you still be able to get it going.

Unpackaging

Untar the ochiba tarball somewhere in your web document root. It doesn't have to be at the top level, it's designed to work within an subdirectory. Once untarred, you should see a directory named ochiba. You can rename this to something else - "imgboard" or "album", for example.

Permissions

There are three directories whose permissions should be modified as the web server process needs to be able to write to them. They are img/, thumbs/, and /tmp/ochiba-cache/. Ideally, they will be chown'd to you:apache and given mode 770, to prevent other users of your system from accessing those directories. If you do not have the administrative access to make those directories group owned by the web server process, you can make them mode 777.

Additionally, if you are using sqlite, the sqlite database file will also need to exist in a directory that is writeable by the web server process. This should not be at a location within the web-accessible file space! Change the ownership/permssions of this directory as above.

htaccess

Ochiba depends on Apache's mod_rewrite to redirect requests to the proper file. The included .htaccess file configures the rewrite engine as needed. If access to the rewrite engine is not available (either because Apache wasn't built with mod_rewrite support, or because the FileInfo override is not available), you will get an error.

Additionally, the included htaccess file includes a snippet that can be used to prevent others from directly linking the images in ochiba - please review and tweak as necessary if you want to enable this feature.

conf.php

You will have to make 2 separate sets of edits to the conf.php file (you'll see why in a moment). The first time, modify the DB and TRIPCODE_SECRET parameters. DB should be in PEAR::DB DSN form - examples are included. TRIPCODE_SECRET is an important string that you should set to something very long. You won't ever have to type it again. However, changing this at a later time will alter how tripcodes are calculated, so don't just put in something you plan to change later.

If you are planning to use ochiba in "photo album" mode, you should change the parameter FEATURE_RESTRICT_POSTING to "ADMINS" (it is "false" by default). If this feature is turned on, only certain people (identified by their tripcode) can post - by setting it to "ADMINS", only the admin user (see below) will be able to post. If you want others to be able to post as well, set this to a comma-delmited list of tripcodes.

Installing the database

Now go http://your.site/path/to/ochiba/install.php. This will will perform a few checks to make sure things are going to work (it is not an exhaustive test, more of a sanity check). Then, it will attempt to create the database file and load the schema.

You should get rid of this file (install.php) once you have successfully created the database).

Setting the admin user tripcode

Now, go to http://your.site/path/to/ochiba/admin. You'll get an error about the administrative tripcode not being valid. That's OK. Type in your tripcode. You'll get another error about the administrative tripcode being invalid. That's OK. Copy the tripcode as reported, and set the ADMINS parameter in conf.php to this value.

Creating a category

The only thing left before you can start posting images is to create a category or two. Return to the /admin page. Now that you've entered the admin tripcode in conf.php, you should see a page that reports no categories, and an "Add" link. Click on it. Fill out the information. The "abbreviation" option is an important one - it will serve as the "URL" for that category (ie http://your.site/ochiba/abbr), so don't make it too long and only use letters.

About tripcodes

One of ochiba's goals is to dispense with the traditional user accounts often found in other software. In its place, it uses tripcodes, which are a hash of a user-specified string, not unlike the password hash used by Unix system accounts. By default, it uses a truncated md5() hash of the string appended to the site-wide TRIPCODE_SECRET string.

Thus, though anyone posting to the site can post as "joe", only the real Joe know the string that will generate a tripcode such as "5lOhkPE32x". For most visitors of the site, then, the tripcode is an identifier (more so than a name).

Administratively, tripcodes are also used to identify admin users, moderators, and other users that have special privileges. In place of a user database, the conf.php file stores these particular tripcodes as string. When a user with a tripcode cookie that matches one of these special privileges, additional features in ochiba will become available to them.

Users can "set" their tripcode (ie login) either by posting something, at which time their tripcode will be cookie'd, or by going to the /admin URL and entering it there, again at which time it will be cookie'd though without requiring a post. If their tripcode isn't special as considered by conf.php, nothing will happen beyond that.

Posting/replying

To post an image, click the "Post" link that appears in the ochiba menubar. This will create a new image "thread". A thread starter specifies the title (topic) and keywords for that thread. Enter the information as indicated:

  • Name: the name of the poster. This is required.
  • Tripcode: a tripcode string. Though this isn't required, it is strongly recommended. For all users, a tripcode is required in order to delete an image later - if an image is posted without a tripcode, it cannot be deleted except by moderators.
  • File: the file to upload. This has a maximum size, by default set to 2 million bytes. The following image formats are handled: GIF, JPEG, and PNG (file extensions are not significant - ochiba will examine a file using ImageMagick's identify to discern a file's type. If a user is listed in FEATURE_ZIP_UPLOADERS, a zip file can be specified here (the maximum file size still applies, however).
  • If FEATURE_MULTIPLE_UPLOAD has been enabled, more than 1 file can be uploaded per POST. This feature requires Javascript to generate additional input elements, up to the number specified by this parameter (use false to disable it). When enabled, a button labelled Another file will appear once the first file has been specified. This feature will not work in conjunction with zip files- only multiple image files will be processed.
  • URL: this input will only appear if FEATURE_FETCH is set to true (it is false by default). If enabled, you can specify an image URL to download and post.
  • Title: a title for the image thread. This is not required.
  • Keywords: keywords for the image thread. This is not required, but should be specified if the keyword filtering is to be used.
  • Categories: at least one is required. By default, an image can be placed in multiple categories. This can be changed via FEATURE_MULTIPLE_CATEGORY in conf.php; if set to false, only one category is allowed.
  • Verification: an image with some blurred text will appear next to this box. Enter what it reads (case is insensitive).
  • Comment: enter a comment. Not required if an image is being posted.

Replying to a thread is accomplished as above, except by clicking the "Reply" link that appears below a thread starter. The dialog is mostly the same, except the Title, Keyword, and Category options are not available as they only apply to the thread as a whole and can only be set by the starter of the thread.

Modify/editing

A thread starter may modify their post. The title, keywords, and categories can be changed. As none of these are applicable to replies, replies can not be modified in this way.

If you are an admin user, you can also modify the comment text, both for thread starters (by selecting the "Modify" link) or for replies (using the "Edit" link).

Deleting

Anyone can delete their own posts. Moderators can delete any post.

Replies are simply deleted. Thread starters, on the other hand, are only deleted if there are no replies in the thread. This is so someone cannot delete the context within which others may have posted replies.

MODERATORS can do a "thread delete" from the /mod page - by specifying a thread number, the entire can be deleted.

Banning

Moderators can ban users via their IP address. If you are a moderator, a "Ban" link will appear for each thread starter and reply. To ban that user IP, click on the link and review their IP address. SQL "globs" can be used, such as 192.168.0.% to ban an entire subnet.

Bans can be reviewed and managed (ie removed) on the moderator's page /mod.

URLs

ochiba uses special urls to do things, kind of like a command line. Categories are referenced by their abbreviation (eg /photos). These are the other magical URLs:

/all
If FEATURE_SHOWALL is enabled, then this will merge all categories into a global category.
/rss
If FEATURE_RSS is enabled, /rss will return an RSS document for "all". Typically, you would append a category via /rss/category.rss (note that /rss/all.rss doesn't work- use just /rss). If you have RSS turned on, appropriate links will appear on the bottom of the category pages.
/admin
Administrative features are available here: managing categories and flushing the cache. To access this page, you must have a cookie'd tripcode that matches the ADMINS configuration parameter.
/mod
Moderator features are available here: managing bans. To access this page, you must have a cookie'd tripcode that matches the MODERATORS configuration parameter.
/keyword
This is the most interesting URL. It allows you to do on-the-fly, virtual albums using terms found in the keyword field. For example, the URL /keyword/foobar will generate a virtual image set of any image threads with "foobar" in the keyword field.
Obviously, use of this feature takes some care in properly keywording all of your images. Also, it's just a string match, so /keyword/foobar will turn up a subset of /keyword/foo.
As of ochiba v0.9.2, a 2nd parameter to /keyword can be added to further filter based on category. For example, /keyword/foo/bar will return matches to keyword "foo" in category "bar" only.
/search
This is somewhat similar to /keyword URL, except it does a simple search and returns them in a "flat" view (no threads). The url is as /search/foobar, which will search for any images with "foobar" in the title or keyword fields. /search/foobar/comments will search for "foobar" in the comments field. Generally, you can just use the "Search" link and form interface for handling this, rather than muck around with the URL.
As of ochiba v0.9.2, a 3rd parameter to /search can be added to further filter based on category. For example, /search/foo/comment/bar will return matches to search term "foo" in comments of category "bar" entries only.
/stats
This one is available if you enable FEATURE_STATS. It shows statistics on each category (how many images, threads, views, etc), popular keywords, and lists the top viewed images. Typically, if this is made viewable, people will abuse it and drive up image views for certain images, so use with caution.
Note: stats are not available if MySQL is used as support for views is not available in older versions of MySQL. Popular keywords and top viewed images are available.

conf.php parameters

Here, I would talk about all the parameters in conf.php, but for now, just read it because it has comments.

Caching

Caching is currently only available when sqlite is used for a database. Then, the following pages are cached when FEATURE_CACHE is enabled:

  • Individual category pages (ie /photos or /photos?p=3). This includes the meta-category /all.
  • The stats page, if enabled (/stats).
  • RSS pages (/rss or /rss/photos)

Other pages, such as detail pages, keyword pages, searches, etc are not cached. Whether a cached file is read or not is determined by comparing the age of the cache file with the age of the database (which in sqlite is a file): if no changes to the database has occurred since the cache file was written, the cache file will be read, otherwise, the page will be generated dynamically and a new cache file written. It's not enormously intelligent, but should work well in medium-to-heavy traffic. Please note the performance issues, however.

Cache files are written to /tmp/ochiba-cache/. If you are running multiple instances of ochiba, then you must change the CACHE_DIR parameter in conf.php to prevent separate ochiba from mixing up cache files. Also, this directory is typically pruned of stale files by system-wide /tmp-cleaning scripts; if you move the cache directory out of /tmp, please make sure to set up some system to make sure the directory is cleared of stale files periodicallly.

Performance considerations

As a dynamic PHP application, ochiba's performance out-of-the-box isn't exactly breathtaking. The use of a fairly "heavy" templating system, while greatly simplifying the process of tweaking the output HTML, has its costs. Caching is enabled by default, and that really helps. However, there are some other things you can do to make it perform better.

View counting
View counting, while a nice feature, is probably the single biggest detriment to performance because each view results in a database update which results in a cache refresh. ochiba has a parameter FEATURE_COUNT_VIEWS that you can set to false, in which case you lose that feature but gain a lot more cache hits in busy installations.
Compressed output
Pages can get fairly large, especially if there are a lot of comments. Compressing the output can save on bandwidth and in many cases make the site appear snappier. It's beyond the scope of this document to fully go into this, but adding: 
	php_flag zlib.output_compression On
	php_value zlib.output_compression_level 5
to your htaccess file is one way to go about it.

Tweaking

HTML
Most of the output can be found in templates/. These are HTML_Template_IT templates, so you'll be faced with a scary amount of junk. Try not to break the logic in the templating markup.
Site-wide look
templates/site.tmpl contains the template for the site as a whole. It's intentionally left pretty bland. Edit this file if you want to "redesign" the look and feel to match your site. You can even get rid of the auto-generated menu, if you want, and create it statically as you see fit- it's only there for convenience. The only thing you should leave are the css reference and the {CONTENT} placeholder, which is where individual page content goes.
Strings
Some strings that are not found in templates are found in includes/strings.php.
Style
The base stylesheet is base.css, which defines primarily the default layout. A second stylesheet (ochiba.css by default) defines more of the "design" (ie colors, backgrounds, etc). If you want to alter the style, create a new css file following ochiba.css as an example of overriding base.css and create a <link> element in templates/site.tmpl. The preferences system will automatically detect new styles created this way and present them as options to the user.
For help regarding ochiba's CSS and styling, please visit the support forum

Custom comment parsing

Ochiba, by default, doesn't do anything with comments except run them through stripslashes() and htmlspecialchars(). However, you may wish do you do your own processing to do things like make links out of things that look like URLs or handle quoting. To this end, there is one programming "hook" you should look into if you want anything like this. When it comes time to format the comment, ochiba will look for a function called custom_comment_format() - if it finds one, it'll send the comment from the database to it. It should return the comment after formatting.

An example is included, but disabled. In index.php, a line that includes a file called custom.php is commented out. You'll find this file in the includes/ directory. It contains a sample custom_comment_format() function that does three things - links HTTP URLs that appear inside brackets (< >), highlights text that looks like a quote(> blah blah blah), and links other ochiba entries (>>123). Customize this function to suit your needs, then uncomment the line in index.php to activate it.

License

Ochiba is released under the GNU General Public License, a copy of which is included in the ochiba distribution (see LICENSE.txt).