Instructions for setting up Crafty Scrapbook

Hardware Requirements:

You can run everything off the same box, or you can run the database on a different machine from your application server(s). For high scalability, you can even run your web server on a separate machine from your application server, although that setup is not discussed here.

The app server should work fine on any machine that supports Java, although I have only tested it on Linux and Mac OSX.

The database server runs Postgresql. I have only tested it on Linux and OS X, but it should be fine on any platform Postgres supports. The database box should have enough disk space (preferably 10+GB) to store all your pictures and movies.

Software Requirements

• PostgreSQL 7.3
• JDK 1.4
• Ant 1.5
• Tomcat 4.1 (only!)

Setting Up the Database Server

1. Install PostgreSQL Server. I'm not really a Postgres expert here, so if you need help your best bet is to consult the PostgreSQL documentation. There are many ways to download the bits -- it comes standard (as an optional install) with Red Hat Linux. Or you can download it from the PostgreSQL site here. Previous version of crafty have worked with just about every version of Postgres, but Crafty 0.2 requires PostgreSQL 7.3 or higher.

2. Create and configure the photo database. Once you have successfully installed PostgreSQL, you will need to set up a database to sick your photos and movies in. There is a preconfigured database you can just load, or you can run the SQL setup scripts in the code/sql directory. Loading the preconfigured database is the simplest way to go, and is the procedure discussed here.

steps:

• Enable remote access. In the <data directory> selected above, edit the pg_hba.conf file to allow for remote access into postgresql from your Tomcat box. This step can NOT be skipped. Even if you want to run Tomcat on the same box as postgresql, you must enable network access for localhost.
• Start postgresql. As the user who owns the process, (frequently 'postgres'), from the command prompt type 'postmaster -i -D <data directory>' Be sure the partition you put your data directory on has a lot of disk space. This is where all your stuff will live.
• Create a database. The default name for the photo database is "refdb", you can change this if you like, but you will then need to modify one of the config files for the app server. (See below.) From the command prompt type 'initdb' and then 'createdb refdb'.
• restore the data in the sample database into the database you set up in the previous step. From the code/sql directory,

  ./restore_database.sh sample_database.tar refdb

• (optional) read the postgres docs and further customize the installation to meet your site needs.

Setting up the Application Server

1. Set Up Java. You will need JDK 1.4 or newer installed on your machine. Crafty will not run on JDK 1.3 or earlier. Download it here.

2. Set up Ant The setup script is requires ant. Get it here.

3. Get Tomcat Although Crafty will almost certainly run on any servlet container that supports the servlet 2.3 API, Tomcat is the only servlet container that is currently supported by the install scripts. download it here.

4. Configure the servlet engine In case of confusion, please consult the Tomcat Documentation. For version 0.11 this step is much simpler.

Be aware that Crafty Scrapbook's install script overwrites the normal tomcat config files web.xml and server.xml with versions of these files found in crafty/config. So if you have any preferred custom settings above and beyond what's required to set up Crafty Scrapbook, make sure this is where you put them.

• Tomcat installation requires that you configure two environment variables, JAVA_HOME and CATALINA_HOME. The deploy script needs to know where your CATALINA_HOME is too. At the top of the file crafty/build/build.xml, find this text: <property name="catalina_home" location="/Users/travis/tomcat"/> and replace "/Users/travis/tomcat" with the location of your tomcat installation.
• If your database is on a different machine from your app server, tell Tomcat what machine the database is running on. Edit the file crafty/conf/server.xml. Search for the text "<value>jdbc:postgresql://localhost:5432/crafty</value>" and replace 'localhost' with the name or IP address of your database machine. When you were setting up the database (above), if you gave your database a name other than "crafty" you must change this setting here as well.

• Run the Crafty Scrapbook install script. From crafty/build, type 'ant'. This should create the webapp, move it into tomcat, and move over the config settings into tomcat as well.

5. Launch the servlet engine. In Tomcat, the bin/ directory constains a cript named startup.sh. It is important that this script be run from the tomcat directory, and not the tomcat/bin directory, or the relative paths required by Tea will break. To do this, type 'bin/startup.sh' from your Tomcat directory. There may be a better way to do this but I don't know it yet.

Special note for linux users
The code that handles file uploads uses javax.swing.ImageIcon. This class has to be able to talk to a running version of X windows. You must start tomcat locally, or the VM will not be able to connect to the display. ssh'ing into the box and launching tomcat remotely will cause the upload feature not to work. You can work around this by setting an environment variable that casues Tomcat to launch java in 'headless' mode.

Monitor these logs for clues if things go south: logs/catalina.out, logs/localhost_log.(timestamp).txt

6. Connect in the web browser Unless you have altered the main port number setting for Tomcat in server.xml, this app should be running on port 8080. Connect to it in your web browser: http://localhost:8080/crafty/ You will need to log in as the admin user in order to see the initial test content. By default the username is 'Joe Admin' and the password is 'admin'. You should be good to go!