Timothy Manual

Introduction

Timothy is a cloud based file archive designed to document your work. It is a world wide web browser based application where you can upload and organize your files. Timothy stores your file in a hierarchy of categories similiar to a disk drive.

Timothy stores your file with information about your file which explains what it is and how it fits. Users make better filing decisions with this information available.

This manual covers:

Basic Operation

Documents are stored by Timothy in categories (or folders),and any category may contain more categories. Each category yields a tree, on which each subcategory is a branch and each document a leaf. A document has a name. However, it is identified by the list of each category you must traverse to reach the document, with the last item on the list as the document name. This list is called the path, and it is written as one long string with a slash between each branch. Thus this document is:

/Documentation/manual.html

One may display this document by typing its full path in the location box of your browser:

http://[server.com]/manager.py/Documentation/manual.html

One may drill down to this document by going to the root and clicking on the Documentation category, then on the Documentation page clicking on Manual.html. You should see the full path in the location box of your browser.

Meta data

Meta data is data about data and is what makes storing and finding files easy in Timothy. In Timothy, meta data refers to six items:

Path
The list of categories you must traverse to find the document
Author
The creator of the document
Title
A concise description or Long name for the document
Name
Together with the path, how Timothy finds the document
Abstract
A long description of the document
Mime-type
A technical description of the format in which the document is stored. Your browser uses this information to display your document. Change it at your peril. We allow you to change the mime-type if your browser fails to call the correct program when you display the document.

Timothy will search the Author, Title,and Abstract to find your document.

Timothy displays the Author, Title, and Abstract for each file in a category. This feature allows you to describe the contents of your archive and how it is organized. Others can use these descriptions to choose where their own work is to be stored.

Searching

Timothy displays a navigation column to the left of the screen. There are buttons for various purposes and a search box. Timothy will search for the words typed into the box in the Author, Title, and Abstract and return a list of documents found.

If you enter more than one word, Timothy returns those items containing both words (a logical "and"). You can search for either word (a logical "or" by inserting a vertical bar (|) between words. You can also use an ampersand (&) for "and." Thus:

brown cat or brown & cat
Returns a list of documents about brown cats.
brown | cat
Returns a list of documents about either brown things or cats.
Returns a list of documents about cats or about brown things.

Buttons

Timothy has several buttons in the left navigation column:

Root
Displays the root of the document tree.
Upload
Transfers a file to Timothy for storage. Timothy displays a

dialog box so that you can provide the meta data as well as the file from your local disk.

Create
Creates a new category. Timothy wants meta data for

categories as well as files.

Current
Returns to the current category. This button shows the

category of an uploaded file.

Create

Categories are added using the create screen. Timothy stores an abstract describing the category and requires a name and a category. Names must be unique within a category.

Abstracts are displayed on the category listing for each subcategory. They should be written to assist you in making filing decisions but short enough to keep the parent page uncluttered.

For example:

Category: shore house

Abstract: travel dates, guest lists, upkeep chores

Upload

Files are added to Timothy using the upload screen. Three of the meta data Timothy uses are entered here: title, author, and abstract. Timothy uses the disk file name for name and determines the mime-type from the file suffix.

If the file exists in the category, Timothy will append a version number to the existing file and save the uploaded file under its name (without a version number).

Here you also assign the category of the file. The default is the current category

Edit

Each item, document or category is listed with an Edit button. The Edit screen allows you to change the meta data about the select document.

Among the data is the mime-type. This is an internet standard way of describing the kind of file. Timothy uses this datum to tell your browser what program to call when down loading this file. If you change it you may not like your results.

At the bottom of the screen is a URL for outside parties. Emailing this link will allow your correspondent to download only this file.

Drop

Use this button to remove the item from your database. Once pressed the document or the entire category is moved to the superceded category. Your system adiminstrator can remove items from superceded.

Improving your site

Configuration

There are server configuration items (see Administering below) that effect Timothy's appearance. These items may be changed using the post_config.py script:

[Your Server]/DocMgr/post_config.py

These items are:

Brand
The word or phrase that appears at the top of every page,

by default "Timothy Document Manager".

logo
The image file that appears at the top of every page.
stylesheet
The cascading stylesheet file to use in rendering each

page.

cat_icon
A small image to be displayed to the left of each

category entry in a category.

doc_icon
A small image to be display to the left of each document

entry in a category.

stylesheet
Cascading style sheet to use when rendering Timothy.

See below

Cascading style sheet

Timothy is designed to produce semantic html markup and use cascading style sheets to render each page. One may point Timothy to your stylesheet using post_config.py. Several tags have an id that you may use as a selector:

header
The top of each page where the logo and Brand are displayed
logo
The logo image
navigation
The section with the navigation buttons and search

box. Display in a left hand column by default.

content
The section where the page content is displayed
footer
Section across the bottom of the page where, by default, the copyright appears.

Each entry in a category listing is a row in an html table in the division "content". Each element of the entry is also identified by a class:

There are also two classes of buttons:

Adding explanatory documents

Timothy is designed to display information about categories and documents to inform the user on how the site is organized and what documents contain. HTML and Scalable Vector Graphics files can be added to compliment this information.

Timothy has two mime-types, application/timothy-html and application/timothy-svg which will be rendered as Timothy pages. This manual is such a document and its mime_type is application/timothy-html. Upload your file to Timothy who will assign a mime-type based on the suffix in the file name. Then edit the entry created and change the mime-type. Timothy will render the document as an explanatory document.

Adding databases

One timothy installation may support multiple databases or instances. Additional database will allow finer grained security and may better serve differing user groups. See setting up databases below under Administering Timothy.

Administering Timothy

Configuration

Timothy is configured in three places, the file /opt/timothy/timothy.conf, the config table in the database and in the Apache configuration.

timothy.conf is the source of the database connection information. Once the connection is established all other setting are in the database. timothy.conf is divided into sections which begin with a word enclosed in brackets like [this] and called a heading. Each heading must begin on the first character of a line and should be the only thing on that line.

Each section, other than the default, sets forth a different database and must be setup in conjunction with a ScriptAlias in the Apache configuration so that [foo] defines a connection made when a user asks for /foo/manager.py. Thus

Apache: ScriptAlias /foo/ /opt/timothy/cgi-bin/

timothy.conf:

[foo] host=localhost port=5432 database=foo user=docmg password=lljg;lkj5

If no other option exists timothy will make a connection using the default section.

Generally Timothy makes a connection as a user you define. On installation, Timothy will use the database administrator credentials from the default section to create the user docmgr and initial database.

The items admin_database, creator and create_password are those administrator credentials.

Setting Up Databases

Timothy supports multiple databases on a single server. Creating a second database is a three step process.

  1. Create the database
  2. Add a new instance to timothy.conf
  3. Add a new ScriptAlias to the Apache configuration.

These three steps are performed by installTimothy.py using the default section of Timothy.conf.

Create the database

Start a psql session at the command prompt:

psql --host=localhost --username=docmgr timothy

Create the database:

create database tim2;

Create the tables and other schema items:

\i /opt/timothy/sql/Schema.sql

Setup the node table for the root and superseded nodes:

\i /opt/timothy/sql/setupNodes.sql

Import meta_data into the mime_type, template and html_field tables:

\i /opt/timothy/sql/meta_data.sql

Return to the command prompt:

\q

Add a new instance to timothy.conf

Instances of Timothy are named. This name appears as a section in the timothy.conf file and as a ScriptAlias in the Apache configuration. Sections begin with the name in braces and contain connection information. For example

[tim2] host=localhost database=tim2 port=5432 user=docmgr password=995zk

Add a ScriptAlias to the Apache configuration

ScriptAlias /tim2/ /opt/timothy/cgi-bin/

The sample configuration file, timothy-http.conf contains instructions to Apache about the contents of /opt/timothy/cgi-bin/ that should be present in the Apache configuration and you may only need an additional ScriptAlias above.

For differing options with different instances consider using a <Location> section with is selected based on the URL (see security below).

Keep the <Directory> which should apply to all instances.

Security

There are two ways to limit use of your site, by script or by database. Each method uses the Apache web server to authenticate the user and to limit access to specific users. Both methods may be used on your site.

Apache will limit use to a specific object on the servers disk through a <Directory> section or to specific URL through a <Location> section.

Objects available to a Timothy server are databases, and scripts.

Scripts shipped with Timothy may each have their own set of allowed users. Databases, or a timothy instance, are just a directory of scripts from Apache's point of view.

Scripts

retrieve.py
Returns a specific documents based on the path following the script name.
ldt.py
Look-don't-touch returns browseable pages for categories and the documents themselves. Users may see the database but not change it.
manager.py
Complete access to the database, browse, create categories, upload documents
post_config.py
Change the configuration settings

Apache access controls

The Apache Manual has a tutorial, Authentication, Authorization, and Access Control which describes basic issues in access control and explains how-to configure Apache for access control.

The files timothy.conf and timothy-http.conf that ship with Timothy contain configuration items for a second Timothy, tim2.

Timothy-http.conf is a sample of the Apache configuration entries for timothy. Timothy relies on ScriptAlias commands to point Apache at Timothy's cgi scripts. This accompanied by a <Directory> entry setting options consistent with cgi scripts.

The <location> tag configures the URL http://[Your Server]/tim2 as a secure site that requires a username and password for access. The commands ask for a Digest type which means passwords will be encrypted before transmission to [Your Server]. The commands point Apache at a password file created by htdigest which contains a database of users with their passwords.

Apache several schemes for storing user data and authenticating the users. We choose the Digest type for its encryption and a htdigest disk file for its simplicity.

Files used by Timothy

Timothy.conf

Timothy.conf contains information on how to connect to the Postgres database server and the Timothy database. The install scripts require this file, and it is shipped with Timothy.

The install instructions later in this manual describe how to set up this file and to obtain site information that should be included in it.

Once the database has been created during installation, it should not be changed.

Timothy-http.conf

This is a sample configuration file for Apache. The installation section of the manual describes what must be done so that Apache can find Timothy's cgi programs.

Once Timothy has been successfully installed, this file should not be changed.

timothy.css

timothy.css is the cascading style sheet shipped with Timothy. Cascading style sheets control how HTML is rendered by your browser. It is found on your server's disk in stylesheets.

You can create your own style sheets and save them to this folder. (See Configuration, earlier in this document.)

logo.jpg

This is the Daly Web &amp; Edit logo that appears on each page. It is found on your server's disk in image.

You can create your own logo and save it this folder. (See Configuration, earlier in this document.)

Templates

The Timothy folder on your server's hard drive contains a folder called templates. Each of the files in the template folder is stored in the database, and so changes to these files will not directly affect your site.

You can modify these templates and insert them into your database. This is not for the faint of heart. We supply a command, enter_templates.py, which will update the database with your changes. The following section describes how to use this facility.

Installing