====================================== Photo Aspect README ($Revision: 1.6 $) ====================================== Author: Joe Foraci (jforaci [AT] hotmail [DOT] com) BUILDING/INSTALLATION: ====================== These instructions are the same for WINDOWS and LINUX (and probably anywhere else a Java SDK can been installed like Solaris). If you don't have the Java J2SE SDK installed you can get it for free from Sun at http://java.sun.com. Software necessary for building Photo Aspect: --------------------------------------------- 1. Get JBoss 3.2 at http://jboss.org. (This is the application server running the photo album). 2. Get xdoclet 1.2 at http://xdoclet.sourceforge.net. (This is needed for building from the source). 3. Get Ant at http://ant.apache.org. (This is the "make"-like building tool for building from the source). Building Photo Aspect: ---------------------- 1. Look at the build.properties file and set your paths to the JBoss directory and the xdoclet directory (don't worry about "docbook-xsl.home" at all) using jboss.home and xdoclet.home properties respectively. If the path to the JBoss or xdoclet directories have a space you should probably put quotes (") around the path in the properties file or just move them somewhere else. Also, make sure the "ant" executable is in your PATH. 2. Issue the command "ant" in the top directory (the one where "build.properties" is located). Your copy should now build with no problems (Ant will show a "BUILD SUCCESSFUL" message) at the end of the whole build process. IF YOU HAD PROBLEMS WITH THE BUILD: Check to make sure you use at least (or exactly) the versions of software I am using in the build.properties file (JBoss 3.2.1 and xdoclet 1.2b4) to at least make sure that those are not the problem. You could also look into the build.xml file which is what Ant reads to get its build instructions (the line number and message shown when a build fails should give you a good starting point). After a successful build, you should see a "build" directory has been made. Inside of it is a directory called "photoalbum-{version}" (where "{version}" is a version number). Inside that directory is only the necessary files to run the photo album copied from your original JBoss installation. HOWEVER, I RECOMMEND YOU USE YOUR ACTUAL JBoss distribution directory (not the one under "build") for any of the following changes since issuing the "ant clean" at anytime in the future will wipe-out the entire build directory and you would lose all configuration AND database data (not actual uploaded photos since those will be stored somewhere else in a location of your choosing). (IMPORTANT: ALL "server" DIRECTORY PATHS REFERRED TO BY THIS README WILL BE RELATIVE TO THE JBoss DISTRIBUTION DIRECTORY FOR SIMPLICITY. ALL "photoaspect" DIRECTORIES WILL BE RELATIVE TO THE photoaspect SOURCE DIRECTORY.) 3. Go into your JBoss distribution's "bin" directory and run "run.sh" for a typical Linux/Unix shell OR run "run.bat" for the Windows shell. The server should start up with no problems (no stack traces) and you should see something like: "INFO [Server] JBoss (MX MicroKernel) [3.2.1 ..." as the last message on your shell. After the server has started, stop it by pressing CRTL+C. 4. Now you have to initialize the database. Simply copy the file from photoaspect's source directory "src/conf/data/hypersonic/create-tables.sql" to your JBoss server's "server/default/data/hypersonic/localDB.script" file (it may be called "default.script" in versions prior to JBoss 3.2.3), overwriting the file already there. (IMPORTANT: If you are using a JBoss distribution you already had lying around, you will be overwriting whatever is currently in Hypersonic's database. If you know what you are doing, you can just copy the "CREATE TABLE" and "INSERT" statements and append them to localDB.script instead of overwriting it.) (NOTE: localDB.script contains the actual database commands that have been received by the database to insert, modify, and remove data in the internal database (called "Hypersonic") used by JBoss. JBoss enables one to configure our photo album to use many types of other databases instead such as Postgres or MySQL or SQL Server, but that configuration is relatively involved and outside the scope of this documentation.) 5. To set your photo directory (the directory to where all images will be uploaded), you have to edit the evironment entry at the end of the web.xml file in the build/web-inf directory, setting "AbsoluteImageStoreDir"'s value to the absolute path of an empty directory (default "/home/joe/pic-store" is mine :). (NOTE: This location is also where you would configure SSL (see "ADVANCED CONFIGURATION" below) if you wish.) 6. Now deploy Photo Aspect by running "ant deploy" and start the server as in the previous step. Then sign-in to Photo Aspect by going to the address http://localhost:8081/photoalbum-web in your browser (JBoss should be configured to use http 8081 for now, edit same file mentioned in "Using SSL" below) and using the username "admin" with the default password "password". After you have signed in, go to the "Preferences" and change your password from "password" to something more safe. You may as well set the other fields too. You can skip down to "USING THE PHOTOALBUM" to start messing around. ADVANCED CONFIGURATION: ======================= Specifying the administration e-mail contact: --------------------------------------------- To setup your e-mail address as the admin contact you have to edit the evironment entry at the end of the web.xml file in the build/web-inf directory, setting "AdminEmailAddress" to your e-mail (default is "void@host.invalid"). Setting this is OPTIONAL but is, of course, recommended since it can be used to get into contact with you. This e-mail can be accessed through the "About" page so someone can contact you to set up an account send you their images for upload, etc. The address will be obfuscated so that those nasty e-mail harvesters won't actually find a string of characters anywhere in the photo album that contains your actual e-mail address. Using SSL: ---------- Stop JBoss. To use SSL you have to edit the evironment entry at the end of the web.xml file in the build/web-inf directory, setting "UseSsl" to "true" (default is "false") and "SslPort" to the port you want to use for SSL. You also have to create a java keystore with the Java "keytool" program (call it identity.jks) and place it in JBoss' server/default/conf directory so it can be read by the server. Then you need to edit the jboss-service.xml file in server/default/deploy/jbossweb-jetty.sar/META-INF directory. Specifically, find the portion of the file with a comment that says something like: "Add a HTTPS SSL listener on port". In the XML elements that follow you can configure your desired SSL port, the path to the keystore (should be "/conf/identity.jks"), and the keystore passwords you used with keytool. Re-deploy Photo Aspect by issuing "ant deploy" in photoaspect's source directory (this is necessary because you changed the web.xml file). Start JBoss. You should be directed to a secure "https" page after signing in to the photoalbum. You should also see that JBoss' output reports that it's using SSL (and at what port) on first access to the photo album. USING PHOTO ASPECT: =================== Uploading photos (requires "privileged"/"admin" role): Go to the "Admin Page" after you sign-in and use the "Add an image" form to submit a new one. It will be uploaded to the photo directory you configured, and re-sampled down to reasonable dimensions. You will be automatically redirected to the photo and get a confirmation message. Deleting photos (requires "privileged"/"admin" role): Go to the photo and press the "Delete" button. Inserting Persons/Users (requires "admin" role): Go to the "Admin Page" after you sign-in and use the appropriate forms ("Add a person"/"Add a user"). Inserting Categories (requires "admin" role): Go to the "Admin Page" after you sign-in and use the appropriate form ("Add a category"). If you want the category to use an image which didn't come with the Photo Aspect distribution in its "src/web/images/category" directory, then you must put it there yourself and re-deploy Photo Aspect by issuing the "ant deploy" command in photoaspect's source directory. Add a news item to the main page: Go to the "Admin Page" after you sign-in and use the appropriate forms ("Add news"). The news and headline can contain HTML tags for formatting. THANKS AND CREDITS: =================== Thanks to Gunter Zeilinger whose build.xml and directory structure for dcm4jboss served as an example for this project. Not to mention introducing me to JBoss :)