Installing a HyperCities Instance

This page discusses creating a new, fresh HyperCities installation on a server. It is intended for a system administrator. Installing HyperCities requires creating a new MySQL database, and may involve altering PHP settings and some server settings. It will also involve upgrading to PHP 5.3 if a lower version of PHP is installed.

API Keys

The front end uses Google Analytics to track usage. If you choose to enable this feature, you will need to acquire a key; it can also be disabled by setting HyperCities.config.EVENT_TRACKER_ENABLED to false in scripts/config.js, and deleting the code from the end of index.php.

HyperCities uses OpenID for authentication. This package includes all of the code required to authenticate using OpenID, Google, Facebook, Yahoo!, MySpace, AOL, and Twitter, but Facebook, MySpace, and Twitter require keys or secrets to allow authentication. Please see these providers' websites if you wish to use them; your HyperCities installation must be registered with each individually, and the registration process varies from site to site.

System Requirements

This guide will assume that HyperCities is being installed on a server similar to the development and production environments, which have the following configuration:

• Linux (Red Hat Enterprise Edition, 5.4) or CentOS 64-bit
• Apache 2.0
• MySQL 5.1
• PHP 5.3

These specific versions of Apache and MySQL are recommended, but others may also work. If you have success installing HyperCities on other configurations, please contribute your notes to the HyperCities Support Forum at http://groups.google.com/group/hypercities-support.

PHP 5.3 is the minimum required version; earlier versions will not work with HyperCities. For help upgrading to PHP 5.3, please see Upgrading to PHP 5.3.

Installing the Code

HyperCities can be run from any directory on the server; it does not have to be run at the server root. Uncompress the files into the desired directory on your server, and configure your server appropriately to point to this directory.

Next, create a directory for user uploads, with 775 permissions. On our server, this is in /data/hypercities/upload. After this, in the directory in which the code was installed (where index.php is stored), create the symbolic links uploadedImages, uploadedAudio, and uploadedKml to the upload directory. These links should have 777 permissions.

To use Open Id (i.e., to allow users to login with Google, Facebook, etc.), create a directory called “oid_store” and set the permissions to 777. This will allow the web server to store user information. Omitting this step may cause login attempts to fail silently with a blank page.

Setting up the Database

To set up the appropriate database structure, first create a database, which can be named as you see fit. You may also wish to create a user for hypercities at this point, with only INSERT/UPDATE/SELECT/DELETE privileges.

Two SQL initialization scripts are included, hc_db_init_content.sql and hc_db_init_blank.sql. hc_db_init_blank.sql sets up the database structure, and populates some configuration tables that track data types with necessary constants, such as object types. It also creates a super user. hc_db_init_content.sql does the same and also includes sample cities and sample maps served by the UCLA tile server.

You may use either one. You may also edit hc_db_init_content.sql to bring in only certain maps or cities. If you choose not to use our maps, empty both the maps and maps_profiles tables. If you remove entries from the cities table but choose to keep one or more maps, you must keep all the cities associated with the maps you keep because all maps are associated with a city.

To import the database, run the selected script on mysql as mysql root. We suggest reading through the complete documentation, including the database schema, before running this script, in case you would like to make any changes to the included data. A complete schema is included in this documentation, and an explanation of all the tables is included in Appendix A, "Database Structure."

PHP Configuration

A sample php.ini file is included in the install bundle. The following settings are particularly important:

• display_errors must be 0. Some operations access invalid array indicies without checking if they exist, and rely on failing *silently to produce valid XML.
• allow_short_tags must be 1. Some files use short tags.

HyperCities uses both mysql and mysqli (mysql improved). Both must be installed.

Setting up constants.inc

After acquiring the necessary API keys and setting up the database, API keys and database information need to be added to constants.inc. The constants already exist in this file but are set to empty strings.

Constant Name	Description
DB_HOST	Hostname where database is stored, e.g. localhost.
DB_NAME	Database name.
DB_USER	Username of database user.
DB_PASS	Database user password.
GOOGLE_ANALYTICS_TRACKER_KEY	Google Analytics Key. Optional.
TWITTER_CONSUMER_KEY	Twitter consumer key. Necessary for Twitter OpenID authentication.
TWITTER_CONSUMER_SECRET	Twitter consumer secret.
FACEBOOK_CONSUMER_KEY	Facebook consumer key.
FACEBOOK_CONSUMER_SECRET	Twitter consumer secret.
MYSPACE_CONSUMER_KEY	MySpace consumer key.

Server Configuration

Some features of HyperCities require mod_rewrite directives, including redirecting all calls to {application_root}/collection/{number}.kml to exportCollectionKml.php?cid={number}. This is recommended so that your collections may be viewed in other applications like Google Earth, but not necessary to use HyperCities as an editing tool. The API also uses URL rewriting, so it's important to have mod_rewrite on.

Setting up the Application

Creating cities

Cities must be created in the database; HyperCities does not provide an interface to do this. Here is an example query from the hc_db_init.sql file that adds Los Angeles to the database.

 INSERT INTO `cities` (`id`, `name`, `abbreviation`, `country`, `lat`, `lon`, `zoom`, `thumbnail_url`, `created_at`, `updated_at` ) 
 VALUES (2, 'Los Angeles', 'Los Angeles', 'United States', 34.05220000, -118.24340000, 14, 
       './files/losAngeles.jpg', '2008-12-17 15:46:59', '2008-12-17 15:46:59'
  )

The cities already in use on the main HyperCities website are automatically added to the database by the database initialization script. These may be safely altered and deleted if you remove the corresponding maps.

Creating a HyperCities admin account

The hc_db_init.sql script will create an administrator account in HyperCities named "hcadmin", with the password "password" and id 1. Please change this password as soon as possible in the database. You may change the username, or create other admins, as you see fit.

This user's ID is already registered in the constants.inc file as HC_SUPER_USER and in config.js as HyperCities.config.HC_USER_ADMIN. This user will have the power to edit and delete all objects and collections.

Creating new users

Non-administrative users can be created using the Open Id login. HyperCities delegates all authentication for users other than the admin through Open Id. After logging in for the first time, each user is required to complete a registration form.

To make any "normal" user an admin, change the value of HC_SUPER_USER to their ID in constants.inc and HyperCities.config.HC_USER_ADMIN in config.js, or change their user_state_id to 11. As a guideline, though, the main HyperCities installation has only one admin user, the HC_SUPER_USER.

Configuring root collections

Root collections are the first collections loaded when the user clicks on the "Collections" button. In the main HyperCities installation, these are Public Collections, Featured Collections, Partner Collections, and Class Collections.

These collections must be created manually in the database, because collections created through the main HyperCities interface must have a parent. To do this, create an entry in the objects table with object_type_id 2. Once the object has been created, you must create an entry for that collection in object_mappings that encompass the entire world (-180 to 180 longitude and -90 and 90 latitude) and the maximum time bounds of HyperCities (from 12-31-9999 B.C.E. to 12-31-9999 C.E.). Here is an example query that creates a "Public Collections" collection:

   -- Creating the collection
   INSERT INTO `objects` (`title`, `object_type_id`, `object_state_id`, `description`, `content_id`, `creator`, `copyright`, 
       `owner_id`, `password`, `created_at`, `updated_at`) 
   VALUES ('Public Collections', 2, 1, , , , , 1, NULL, NOW(), NOW());
   
   -- Creating the object mapping:
   INSERT INTO `object_mappings` (`object_id`, `object_state_id`, `marker_style_id`, `kml`, `ne_lat`, `ne_lon`, `sw_lat`, 
       `sw_lon`, `view`, `date_from`, `dateFrom_isBC`, `date_to`, `dateTo_isBC`, `created_at`, `updated_at`, `basemap_id`) 
   VALUES (1, 0, 0, , -90, -180, 90, 180, NULL, '9999-12-31 00:00:00', 1, '9999-12-31 23:59:59', 0, NOW(), NOW(), NULL);

Then, go to the database and find the ID of the newly-created collection, and add it to the constants.inc file, as well as getCollectionList.php. Define constants with both its ID and its name, and add these to the HC_BASE_COLLECTIONS_ID and HC_ROOT_COLLECTIONS arrays; see constants.inc for examples. Add these to the HyperCities.config.HC_COLLECTIONS object in config.js as well, following the example.

At this point, HyperCities should be functioning normally. To test this, try creating some new collections and objects in HyperCities. You may also delete the /install directory if you choose, or move it to a new location.

Deployment Notes

HyperCities has a utility function called HyperCities.util.debug, which is a wrapper for Firebug's console.log control. This allows trace messages to be hidden easily. To prevent these messages from being shown in a production environment, set HyperCities.config.HC_DEBUG to false in config.js.