Exist DB Installation Guide for LS
From GEANT2-JRA1 Wiki
Contents |
Installing eXist
The eXist xml database can be installed in one of the two ways
- As a web application inside Jakarta Tomcat
- As a stand-alone server
As a web application inside Jakarta Tomcat
- Download the eXist war file from the website (1.0 and 1.1 versions are tested with LS. 1.1 is recommended)
- Make a note of the location of the eXist war file (complete path - $EXIST_LOCATION - ex: /home/loukik/perfSONAR/webapps/exist-1.0.1.war)
- Make sure you have Tomcat installed, setup and running
- Make a note of the Tomcat home directory ($TOMCAT - ex: /home/loukik/jakarta-tomcat-5.0.6)
- Make a note of the dns servername ($SERVER_NAME) and port ($PORT) where tomcat is running
- Check if tomcat is running by pointing your web browser to http://$SERVER_NAME:$PORT
- If you don't see tomcat home page, check the logs ($TOMCAT/log/catalina.out) to identify potential problems)
- Edit the server.xml file found in $TOMCAT/conf directory
- Search for the </Host> tag in server.xml (Note: it is the closing 'Host' xml tag)
- JUST BEFORE the </Host> tag, add the following lines (replace $EXIST_LOCATION with appropriate value)
<Context path='/exist' docBase='$EXIST_LOCATION'> </Context>
- Restart tomcat
- To check eXist installation, point your browser to http://$SERVER_NAME:$PORT/exist.
- You should be able to see the exist welcome page
- Scroll down, in the left menu at the end of the page, you can see the Admin link
- Clicking on it will take you to the admin pages, login using username admin (and blank password field)
- Make sure you log out.
As a stand alone application
Downloading Software
Download eXist from http://exist-db.org/index.html#download]. It is suggested that you use 1.0 or 1.1. They work exactly the same, but have different core. Lookup Service was tested with both of them.
Installing eXist
To run graphical installer of eXist enter the following command and select the path for installation when asked:
java -jar eXist-1.0.1-build4311.jar
To run command line installation of eXist enter the following command and specify installation path as a parameter (you should replace $EXIST_HOME with your own selected path):
java -jar eXist-1.0.1-build4311.jar -p $EXIST_HOME
The rest of this document assumes that eXist directory name is under $EXIST_HOME e.g /usr/local/exist.
eXist startup
eXist uses a Jetty server. It is also possible to run it from Tomcat, but it's a little bit harder (you'll need to deploy eXist and COCOON manually). If you decide to use Jetty, remember that it mustn't use the same port as Tomcat, where the Lookup Service resides.
Changing default port
To change the eXist default server port, open $EXIST_HOME/bin/startup.sh file and find OPTIONS line which should look like:
OPTIONS="-Dexist.home=$EXIST_HOME"
Then alter that line adding new port number at the end:
OPTIONS="-Dexist.home=$EXIST_HOME -Djetty.port=8680"
8680 is an example of new port number (default is 8080). This 8680 port number will be used in next examples. You must change it into your own one where necessary.
Running an eXist server
After the installation and configuration has completed, you should be ready to launch eXist. To run eXist server enter the following commands:
cd $EXIST_HOME/bin ./startup.sh
It starts the included Jetty webserver at previously configured port i.e. eXist and Cocoon are installed as a web application, located at http://localhost:8680/exist/
Running the eXist client tool
eXist client can be launched in two ways: first, you may use eXist's GUI, second, you may use the shell mode. Without an action, the client switches to interactive mode and displays the graphical user interface. It is also possible that the client switches to shell-mode and prompts for user input.
GUI
Simply run client script without any parameters:
cd $EXIST_HOME/bin ./client.sh
and enter URL in database login window pointing to your eXist location e.g. xmldb:exist://localhost:8680/exist/xmlrpc
Then connect to the server.
Shell mode
The shell-mode is invoked using the following command (it provides access to a server running inside the Jetty webserver at port 8680 on a local host):
cd /$EXIST_HOME/bin ./client.sh -s -ouri=xmldb:exist://localhost:8680/exist/xmlrpc
When connected successfully you should see eXist database prompt:
exist:/db>
You will find more information about eXist integrated command-line client pointing towards eXist home page.
For Lookup service in perfSONAR Bundle 2.x - Adding two required files to the XML Database
- Once the eXist XML Database has been installed, you need to create a new collection in the xml database and add two files.
- You can download the two files from the links below (do not copy paste the text but save the files. Otherwise you will loose the namespaces as some browsers hide namespaces while displaying xml files)
- You can create the collection and upload the files in any of the 3 ways below.
Via Web based GUI
- You can access the XML Database contents via a web based interface only if you installed eXist as a web application inside Tomcat
- In the exist homepage (usually http://$SERVER_NAME:$PORT/exist if you followed the instructions above), scroll down
- In the left side bar, you will notice an admin link and an orange 'Launch' button (1.0.1 and 1.1.1 versions of exist)
- Clicking on the Admin link will display a web based login page. This section instructs you on how to work with the web based interface. Clicking on the Launch button will download and open a Java application (JINI based) which can be used to interact with the XML database. This application is explained further in the next section.
- Provide admin credentials (password can be blank if not already set) and login. When you are done, REMEMBER TO LOGOUT. The Web Interface is known to behave wierdly if you don't log out.
- Once you are logged in, you have options to:
- Browse collections
- Manage Users
- Log out, etc
- Click on Manage Users to add, remove and modify users of the XML Database
- Its best to start by adding a new user, logging out of admin and logging in as new user
- When adding a new user, provide a username and password of your choice. We suggest providing dba for the 'Groups' and /db as Home Collection.
- You can use the same username and password across all services (but create individual collections per service).
- Once you have created the new user, LOGOUT as admin and LOGIN using the new username and password.
- Remember this username and password as it will be required during installing of LS
- Click on Browse collections to see the existing list of collections in the xml database. This is where all the data is stored
- for perfSONAR, each service needs to have its own collection
- To create a new collection, enter the collection name in the blank (for example: ls for lookup service). Then click on the Create collection button. The collection will appear in the displayed list.
- Click on the new collection in the list to enter into the collection and see the contents. Of course, it will be blank to start with. Here is where you can either manually add the xml configuration (metadata, control, store, etc) or check out the ones which have already been added. You can also remove the existing ones and add new ones (useful if you are managing your xml metadata configuration file for a service such as rrd ma, sql ma, etc)
- For the lookup service, add the two xml files that you downloaded earlier (see section above). Its very easy to add these files. (Make sure you have logged in as a user other than the admin and make sure you provide this username and password during ls installation.
- LOGOUT
Via Application based GUI
- If you download the eXist XML database as a standalone server (not the war file), it comes with a client application. Launching this application (double click, requires Java) will display a login window. It will also require information about the location (URL) of the exist database
- If you download the war file and have installed eXist onto tomcat, you can find the exist xml db homepage at http://$SERVER_NAME:$PORT/exist (if you followed the instructions in this page). Scroll down the page to locate the orange 'launch' button on the left side bar (1.0.1 and 1.1.1 versions of exist). Clicking on that button will launch the application (Java RE required)
- The URL of the eXist XML db is usually something along the lines of xmldb:exist://$SERVER_NAME:$PORT/exist/xmlrpc.
- For a standalone application, the port is usually
- For web application in tomcat, the port is the port where tomcat is running
- After logging in successfully, the menus will allow you to manage users, create collections and add xml files.
- Add the two xml files made available in the previous section for download
- Logout after you are don
Via Command line interface or shell mode
The following examples will guide you through shell-mode of eXist client.
- First create user account for Lookup Service entering the following commands in eXist shell:
exist:/db>adduser lookupservice password: sonar re-enter password: sonar home collection [none]: enter groups: guest user <...> created
These are just examples and you can use other login/password of your own choice.
- Create collection "ls" (or other for Lookup Service storage)
exist:/db>mkcol ls created collection.
- Create two XML files in the ls collection by importing data from example XML files:
exist:/db>cd ls exist:/db/ls>put $PERFSONAR_LS/schema/example-instances/sonar/LS/test/LSStore.xml exist:/bd/ls>put $PERFSONAR_LS/schema/example-instances/sonar/LS/test/LSStore-control.xml
- Set user/group rights if necessary. Use:
exist:/db/ls>chown lookupservice guest LSStore.xml exist:/db/ls>chown lookupservice guest LSStore-control.xml
- Change rights to access these resources if necessary. User lookupservice:guest should have R/W access to both resources.
- It is suggested to use eXist client GUI instead of shell-mode, because commands
mkcolandchmodmay not work in some versions of eXist DB.
