Gordon's WebLog

Here are instructions for a new installation or an upgrade to an existing version.

Download it here 

Etomite Content Management System. Release 0.6.1 (Prelude) Final. April 12, 2006

The following information is intended to be used as a reference when performing both new package installations or upgrades from previous releases. Please read this entire document before proceeding further. Following the directions below will greatly reduce the need to visit the forums for support help. Should you require additional help, however, simply visit the Etomite forums and perform several site searches based on keywords related to the problems you are encountering. Do not open a new topic if there is even a remote possibility that someone else may have already experienced the same problems as this would only serve to further fragment the knowledgebase.

NEW INSTALLATIONS:

The following sections have been copied directly from the Etomite documentation. Please read them fully before proceeding.

Installation Guide

Introduction

This document will help you getting Etomite up and running. You should know a little about *nix style file permissions to get Etomite running. This document only applies to fresh installations of Etomite 0.6 or higher!

Upgrading an existing version?

If you're upgrading an existing version of Etomite, follow the steps outlined in this document, and once you run the installer, be sure to choose the upgrade option. During the upgrade, your site will not be available for visitors! Be sure to make a back-up of manager/includes/config.inc.php (although this isn't required, it's always handy `just in case`) and once you've finished upgrading be sure to check the Etomite configuration!

NOTE-

Currently there is no updater to update to version 0.6.1 from 0.5.3. All installations will be fresh.

Download and upload

Download Etomite from the download section, unpack the zip file and upload all the files to your web space, making sure the directory structure stays intact. As of version 0.5, you can install Etomite in subdirectories of your website. We'll call the location you install Etomite 'path_to_etomite. If you're upgrading, also upload the config.inc.php and settings.inc.php backups you made – upload these to the path_to_etomite/manager/includes directory.

File Permissions

Use your FTP client or a control panel to ensure the following are writable by PHP (chmod 777):

path_to_etomite/manager/includes/config.inc.php

path_to_etomite/assets/cache (See Note Below)

path_to_etomite/assets/images

path_to_etomite/assets/export

Note: All files within the path_to_etomite/assets/cache directory should also have full permissions (chmod 777). The majority of installation problems are a direct result of not having the permissions of these files set properly.

After your config.inc.php file has been written, you may wish to modify the permissions to read only as this will not need to change unless your server or database changes.

.htaccess and Mod-Rewrite

Make sure that your Apache configuration file (httpd.conf) is set to allow overrides and that Mod-Rewrite is installed. This will allow you to take advantage of Friendly URLs in Etomite 0.6 and above.

Prepare MySQL

The Etomite installer needs a database to write the site to, and it will attempt to create one for you. However, your host may not allow the creation of databases from PHP scripts, and the installer may fail (without warning) if it attempts to create a database when it's not allowed to. To combat this either:

* Create a new database for Etomite from your control panel or MySQL administration tool (best option)

* Make sure you're allowed to create databases from PHP scripts

* Use an existing database

Once you've set up an empty database or have a database ready, you can run the installer.

Run the installer

You can now run the installer which is located at path_to_etomite/install. Follow all the instructions, and the installer should run fine. If you're installing Etomite into a database which already contains an Etomite site, be sure to choose a different table prefix than the existing Etomite tables. You can specify a table prefix during the installation.

Delete the installer

To be on the safe side, it's best to delete the installer (path_to_etomite/install/) folder after you've finished installing Etomite.

Login

After installing Etomite, browse to the directory you installed Etomite in. If everything goes well, you should see a basic stock-out-of-the-box Etomite site ready to configure.

Configure

When you first login to Etomite, you will be taken to the configuration settings. Review these settings and make necessary changes (like site name). Use the Save button at the top of the page to save the settings, and your Etomite site is ready to launch. This step is a must. Before you save your settings for the first time, the settings are NOT in the database at all and your site will note work! You can then launch your site by choosing the Launch Site link in the Site section of the admin menu (top left of screen in manager). Alternatively, you can just point your browser to the URL for your site.

You can come back to the configuration setting at any later point to make other changes such as how you want your URLs to be handled/rewritten. Test the changes after you make them to ensure that the new behavior or setting acts the way you thought it would.

END

UPGRADING FROM EARLIER RELEASES

Although some of the changes may seem minor they could cause production sites to become non-functional if steps are overlooked. YOU HAVE BEEN WARNED...!!!

Before you begin

It is always a good idea to perform a backup of your system prior to performing any major upgrades, and this release should be considered a major upgrade to existing installations. A complete backup of your database should be performed along with a backup of the entire code base. It is better to be safe than sorry...

What files need to be replaced?

Due to the vast number of changes to the code base it recommended that ALL existing source code be replaced with the newer code provided in this release.

What doesn't need to be replaced?

Several directories have had few or no changes and can be left in their original state. These directories are assets/images/, assets/export/, and assets/site/. As an option you could simply replace all files and then retrieve any previously modified files from your backup copy.

What changes do I need to make before performing the upgrade?

* Delete your sites assets/cache/etomiteCache.idx.php (etomiteCache.idx for those upgrading from Etomite 0.6 Heliades).

* Delete ALL assets/cache/docid_*.etoCache files.

* The configuration file has changed so have your manager/includes/config.inc.php settings available for editing purposes later in the upgrade.

What won't be changed or replaced by the upgrade?

None of your existing Etomite resources (Chunks, Documents, Keywords, Snippets, and Templates) will be replaced, nor will any new resources be added. All new resources, which are installed during a new installation, will be made available through Etomite.org as optional additions to your existing site(s). You will be required to modify the site_content table as will be discussed next, however.

Okay, how do I modify my site_content table?

There are two preferred methods for modifying the site_content table - pick the one which suits your needs. The first method is to use phpMyAdmin, or your favorite MySQL administration utility, to run the code listed in the assets/docs/dbchanges.txt file after editing it as documented within that file. The second method is to run the install/alter_site_content.php script from within your browser. This script can be run either before or after all other files have been uploaded. This script requires a properly configured manager/includes/config.inc.php file which can either be the original file or the new one described by the installer. Note that the installer doesn't actually create the file - it only provides an example of what the new configuration file should look like. There is a file in the new code base that is intended to be used to create your new file. The best method would be to edit manager/includes/config.inc_generic.php to contain your database settings and then save it as manager/includes/config.inc.php prior to running the database modification script.

All of the steps above have been completed, now what?

Next you need to log into your Etomite Manager, verify your site configuration settings, save the settings, and clear your sites cache. You should now be able to access you website, as well as work with the Etomite manager, without further modifications.

Good Luck...

END

Friendly URLs

This guide will help you getting Etomite up and running. You should know a little about *nix style file permissions to get Etomite running. This document only applies to fresh installations of Etomite 0.5 or higher!

Prerequisites:

Knowledge on how to use .htaccess files, Etomite must be running on the Apache web server, mod_rewrite must be enabled

What are Friendly URLs?

Search engines generally have a difficult time spidering pages with filenames such as index.php ?id=123. To combat this, we'll use Apache's mod_rewrite functionality to transform those ugly URLs into nice URLs such as p123.html, home or even home.html. To do this we need to write two .htaccess files, and change a couple of settings in Etomite.

.htaccess files

We'll need two .htaccess files, one in the main Etomite folder, and one in the manager folder. In the first one, we'll tell Apache to use the RewriteEngine, and how to use it, and in the second, we'll tell Apache not to use it. We do this to stop the manager from being broken by the RewriteEngine.

The first file, to be placed in the main Etomite folder, needs to contain the following:

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

In the first line, we tell Apache we want to use the RewriteEngine. The second and third lines set some conditions, and the last line tells Apache how to rewrite URLs.

Basically we're telling Apache to take everything between the 'p' and the '.html' and append it to the URL 'index.php ?id=', and then to send that file to the client. The [QSA] tells Apache to append the query string to the new URL.

The second .htaccess file, located in the manager folder contains only one line:

RewriteEngine Off

This tells Apache not to apply any rewriting rules in the manager folder.

To add these values, I've included two ht.access files in the Etomite distribution for 0.5.1. Rename them to .htaccess using your FTP program, or copy the values contained in the ht.access files to your existing .htaccess files.

Configuring Etomite

Now we need to tell Etomite to use Friendly URLs. To do this, in the Etomite manager, go to Etomite configuration in the Administration menu. There you will see three options for Friendly URLs:

First, set 'Use friendly URLs' to 'Yes'. Then, specify your can prefix and suffix, but lets leave them as they are for now. Save the settings.

That's it! Open your site, and hover your mouse over a link in your page. If everything's working properly, you should see links like 'p123.html' instead of 'index.php?id=123'. Clicking on one of the links should open the correct page.

Using different prefixes and suffixes

You might want to use different prefixes and suffixes than the default ones. Let's assume you want to have your URL's look like this: 'content123.xml'. Simply update the Etomite configuration to reflect these changes: set the prefix to 'content' and the suffix to '.xml'. All done! You can even leave the prefix empty, and access pages like '123.xml'.

Using Aliases

Etomite 0.5.2 introduces aliases. You can assign an alias to a document, such as `home`, and use that as URI: yoursite/home will point to the page you aliased. Make sure you don't give more than one document the same alias, and that the alias is not the name of an existing folder. You can combine aliases and prefixes and suffixes for even more URL options: /home.html will point to the document with alias `home`. You can even access documents by just typing their ID!

Friendly URL types

To sum up, we have the following ways of accessing your content:

* yourdomain.com/index.php? id=123

* yourdomain.com/p123.html

* yourdomain.com/home

* yourdomain.com/home.html

* yourdomain.com/123

END