Installing XSM
1 - Introduction
Whilst Rectang.com is the expert provider of XSM based web sites and can manage web sites on almost any server in the world you may wish to install it for your own needs. This document explains how you can set XSM up for yourself.2 - Requirements
Java (1.4 recommended)
Maven 2 (2.0.4 or later recommended)
Java Servlet Container (or application server) (tomcat recommended)
3 - Compiling
If you downloaded XSM from rectang.com subversion you will need to compile the application package. If you downloaded from the files / downloads page you can skip this page.
To compile the application make sure you are in the xsm-web directory and type
mvn install
(assuming mvn is installed in your path, if not then consult the maven documentation)
4 - Deploying
The xsm-web.war file should be copied into your servlet contaners (e.g. tomcat) webapps directory.
Your servlet container must not run xsm directly from the war file, but expand it (which is the default)
The directory "xsm/custom" must be writable by the servlet container. If your container is running as root in a secure environment this may not be the default setup.
If necessary you can use this script to deploy the context and ensure the correct permissions:
#!/bin/sh
cd /var/lib/tomcat4/webapps
/etc/init.d/tomcat4 stop
rm -r xsm
mkdir xsm
cd xsm
cp ../xsm.war .
unzip xsm.war > /dev/null
rm xsm.war
chown -R tomcat4 custom
cd ../
/etc/init.d/tomcat4 start
5 - Configuration
There is a demo configuration in CVS now, named xsm_demo_config.zip,
extract that into /etc by default to get you going! You need to make
sure that your servlet container has permissions to write into the xsm
directory created.
If you are not using a unix system, or have no access to /etc
put the configuration somewhere else, but be sure to change the
"xsm.data.dir" to the preffered location in xsm.properties (in the
source tree or xsm.war if using the binary release).
The main directory should contain
- config.xml
- xsm_local.properties
- log4j.properties
- id_rsa (if you intend to use the SSH backend) (not included in the demo, you must create this file using ssh_keygen)
log4j.properties is optional, but useful for debugging! any standard logging configuration should work.
config.xml defines the XSM configuration, curently try:
<xsmconfig>
<admins>admin@demo</admins>
</xsmconfig>
xsm_local.properties contains values that override the defaults for xsm. An important line to include is:
xsm.url=http://mysite.com:8080/xsm
this
should inform XSM at what URL it is installed. This may be "localhost"
for a development site, but when publising it is advised to use a
web-visible address. More information on xsm_local.properties can be found on the next page
id_rsa is a standard private key for ssh connections - make sure it is only readable by the servlet container.
Next is the basic configuration of each site, one sub directory for each site. (This manual configuration step will be automated soon!)
5.1 - xsm_local.properties
Here is a list of the properties and their defaults that you can use in the xsm_local.properties file.
xsm_local.properties can be placed in /etc/xsm, <tomcat_root>/webapps/xsm_local.properties or anywhere in your CLASSPATH
# The directory XSM uses for storing all it's data
xsm.data.dir=/etc/xsm/
# The directory for storing files
xsm.log.dir=/var/log/xsm/
# The directory for storing temporary files
xsm.tmp.dir=/tmp/
# The URL that XSM is installed - this should be a web visible URL unless you are developing an "offline" site
xsm.url=http://localhost:8080/xsm/
5.2 - Site configuration
The default site provided with XSM (in xsm_demo_config.zip explained before) is called "demo" and it's administrator is named "admin" with the same password, you can log in with these details to start editing your new site!
if you add a new user and want to make them an admin as well you will need to edit the "admins" attribute of site.xml's <site> element, changing admins="admin" to admins="admin,newuser".
Note: at the moment if an admin changes his username the admins attribute will need to be edited to reflect the change.
6 - Logging In
Once the installation is complete you will need to restart your servlet container.
Then load up your browser and go to the URL http://localhost:8080/xsm/XSM (your installation may be different).
Here you can log in as user "admin" with password "admin" at site "demo" which will get you started.
Be sure to change admin's password once you are logged in!
