The data directory and conf file

I thought this deserved a special section to make attention to this small fact. eXist stores all its information in a directory called "data". In embed mode you will find it in the {context name}/WEB-INF/data. In external it is the same WEB-INF/data. It can sometimes be advisable to make a backup of this directory ever now and then. No matter how badly something happens to eXist restoring this directory will put everything correct again.

Also eXist gets its settings from a file called "conf.xml" normally you will rarely go into this file, but if need be you might wish to read it and tweak it.

Increasing memorry

If your going to be a full registry then you will most likely need to increase your memorry, otherwise either eXist or Registry webapp may get OutOfMemorry errors. Even on a small publishing registry with eXist embedded in the webapp, if your tomcat is running on default 64m you may experience OutOfMemorry errors.

I would advise for full registries to be at 512m and small publishing registries to be anything above 128m.

**To do this in embed/internal mode, then you just need to give your servlet/j2ee container more memorry. For tomcat you can do this by setting the CATALINA_OPTS variable to "-Xmx128m" or "-Xmx512m" if your a full registry

**In the external eXist case you would only need to change if your going to be a full registry; in which case you look at startup.bat or startup.sh file in the bin directory and change its default setting for JAVA_OPTS to have a -Xmx=512m instead of 128 like it has.

eXist embedded

By default eXist is embedded into the registry web application meaning you don't have to download it or setup any settings. The Registry already has all the necessary libraries to run eXist. The default of the registry though puts all the information (xml data storate) inside the webapp and this in general is not good and is recommended to change because of upgrading or undeploying of the registry would lose the data. You could of course make backups of the data directory and after doing an upgrade or deploy simply copy back over the data directory and restart your servlet/j2ee container. But there is a easier way to make settings use a different directory to store your data:

• Create some other direcotry not under tomcat of where you would like your data to be stored for eXist.
• Copy the conf.xml, and the whole data directory from your {context name}/WEB-INF directory. So inside your directory you should now have conf.xml, data {directory}.
• Using the tomcat Administration GUI, go and change the "reg.custom.exist.configuration" property and point to this directory.
• Be sure to hit "save" then hit "commit changes".
• That is all you, now when data is being stored it is using this new data directory, be sure during upgrades to set that property to your directory. Also note "Windows" OS users normally need to escape there slashes ex: c:\\existstore.

eXist external

If you think you might use eXist for other tasks or wish to play with some of its other features you can do through the web browser. Then you may download it from here. But there are a few settings you may wish to do.

Changing default port: By default eXist runs on port 8080 through jetty. YOu may wish to change that port number. This can be found in the tools/jetty/etc/jetty.xml file to change the port number.

Currently you must do

Getting rid of "match" tags: eXist by default on the "like" or "match" type xqueries where by you search for a substring in the registry, eXist will put exist:match tags around everything that was matches. You need to switch this off in one of two ways.

1.) Go to the "conf.xml" file and you will find a "match-tagging-elements" set to true, set it to false.

Or

2.) In the {context name}/WEB-INF/classes/xsl you will find a file called ExistRegistryResult???.xml file, if you know xsl you could essentially strip out the tags in this stylesheet. The registry always calls the appropriate stylesheet. The ??? is the version number of the queried vr namespace normally now 0.10.

You must do this: Go into your Tomcat Administration GUI or where ever you change the JNDI and change the xmldb.uri to the proper uri. For exist on port 9080 on the same machine it would be: "xmldb:exist://localhost:9080/exist/xmlrpc"

Running the client

eXist has a nice client ability in case you really need to dig into the database itself. Such as inspecting the xml more closely, admin the documents more, run special xqueries, do backups. Normally most of these functions are available through the registry jsp pages, but it can be nicer to have a look at the eXist db if needed. * If your using eXist, you may go into your {context}/WEB-INF directory and there you will see a file called "startclientexample.txt" for you to look at and shows how to go into eXist in shell mode "-s" or gui client then drop the "-s".

In general this is what it says:

*Run this in the WEB-INF directory.

*if you have GUI ability drop the "-s" for a GUI client. Windows and Unix commands are the same except the "/" for the endorsed.dirs area.

Internal/Embed-- ***Windows-- java -Djava.endorsed.dirs=\lib -jar start.jar client -s -ouri=xmldb:exist://

***Unix-- java -Djava.endorsed.dirs=\lib -jar start.jar client -s -ouri=xmldb:exist://

(if your conf.xml and data directory are outside the webapp which is advisable then a -Dexist.home={directory of conf.xml} needs to be added as a parameter)

External-- First I should note the eXternal installations should have client an backup scripts in the bin directory already, but you may also run it with the registry webapp start.jar area if desired or even the eXist start.jar.

* The ouri should be what you have in your xmldb.uri property for the registry.

*here is an example of an exist on the same machine on port 9080

***Windows--java -Djava.endorsed.dirs=\lib -jar start.jar client -s -ouri=xmldb:exist://localhost:9080/exist/xmlrpc

***Unix--java -Djava.endorsed.dirs=/lib -jar start.jar client -s -ouri=xmldb:exist://localhost:9080/exist/xmlrpc

Other client and backup abilities direct to eXist

* See Exist Client Docs for other various commands you will notice that you can run everything by following the commands above with the proper parameters for the start.jar. Remember the client shell is "start.jar client {other params}" and backup is "start.jar backup {other params}"

Setting up users and passwords

In general I recommend to use the default settings for users and passwords in embed mode and usually the same for external eXist mode just have eXist on a non-public url (where by it can only be seen by the registry webapp). But you may wish to have more strict settings on this, the registry webapp can cope with this if you desire. First it will be up to you to setup users and passwords through the client, see above section. Also advise reading the eXist webpage dealing with users. Finally the JNDI properties needs to be changed such as through the Tomcat Administration GUI. You will see xmldb.admin.user, xmldb.admin.password, xmldb.query.user, xmldb.query.password that are available for setting.