1. Installing

Just download the jar-file installer and then either double-click on the jar file or issue the following command:

   java -jar atomojo-server-0.10.0.jar

You should get a GUI-based installer for installing the server. Running The Server

2. Configuring and Running

2.1 Getting Started

The server stores its data on the file system. You must give the server a directory in which it will store the database files. As such, the minimum argument to the server is the database directory:

For example, to store the data in /opt/data

   server /opt/data

The first time the server runs it will create the database and setup the configuration files. You may specify a hostname, ip address, and port on the command line the first to to set the host and address to which the server binds. This information is stored in the 'server.conf' file in the database directory.

By default the server runs over the HTTPS protocol. You can change this by modifying the server.conf file.

The default administrative user has an alias and password of admin.

2.2 Configuring the Server

In the directory used by Atomojo are a number of important configuration files:

• db.conf - lists the databases
• server.conf - configures the server
• log4j.xml - the log4j configuration file
• keystore - the keystore used for SSL

The db.conf file is a simple XML document that lists the databases available to the server. Each database is a directory in which separate feed stores are located.

Initially, this document looks like:

<databases xmlns='http://www.atomojo.org/Vocabulary/Admin/2007/1/0'>
<database href='data'/>
</databases>

You can add databases by just adding another 'database' element. The server will automatically create the database directory as needed.

The server.conf file is an XML document that contains the interfaces/ports on which the service listens and the hosts to which it responds. This document is structured as:

<server xmlns='http://www.atomojo.org/Vocabulary/Admin/2007/1/0'>
<keystore password='atomojo' href='keystore'/>
<interface address='*' port='8080' secure='true'/>
<host name='*' port='8080' database='data'/>
</server>

The host element can optional have an address and port as well. This will limit the host to that specific address and port.

You many have any number of interface and host elements but the minimal configuration has at least one of each.

A * value for the address is wildcard and will bind to all IP interfaces on the machine.

A * value for the host name will allow any host name to be specified.

2.3 Setting up SSL and Host Certificates

In the database directory a 'keystore' file is created. This is a keystore that can be mained by the keytool command-line tool from the JDK. By default, it contains a certificate for localhost.

You can add your own host names to this keystore by the keytool command as follows:

keytool -keystore {path-to-keystore} -genkey -alias {host}

where {path-to-keystore} is the keystore file in database directory.

All the standard methods for maintaining and importing certificates to a keystore via the keytool program apply.

There is a lot of good information about generating a real certificate out there on the web. Most SSL certificate providers have instructions for Apache's Tomcat server (e.g. creating a CSR from GoDaddy or general information on SSL and certificates from Sun). Just follow those instructions as Tomcat users the JDK's keystore/keytool system as well.

Keep in mind that atomojo ships with a self-signed certificate. Certain programs will have an issue with that certificate and may not allow you to interact with the server without first approving the self-signed certificate.

You have several options for development testing:

1. In the browser you can approve the certificate once by going to the https address of the atomojo server.
2. You can create a real certificate for testing and set up an alias in your hosts file.
3. You can disable SSL by setting 'secure' to 'false'.
4. In Java, you can import the certificate as a trusted certificate. See http://java.sun.com/docs/books/tutorial/security/index.html or http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security6.html for tutorials on this.

2.4 Configuring Authentication

Users and associated authentication services can be controlled by adding an auth element to the server.conf:

<auth name="my-auth" class="org.atomojo.app.auth.FileAuthService" href="auth"/>

There are two implementations provided:

• `org.atomojo.app.db.DBAuthService - stores the users in the derby database (the default)
• `org.atomojo.app.auth.FileAuthService - stores the user in an XML document

Each of these implementations implements the interface org.atomojo.app.auth.AuthService and a deployment can use a custom class.

If the file-based authentication service is used, the file must have the structure:

<auth xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<group name='admin'/>
<user id='e01cba54-9ea3-4dcd-9e57-f0563a29e49e' alias='admin' password='admin' groups='admin'/>
...
</auth>

where groups must come before users.

Note that the 'user' element may have the same structure as when you add a user via the Admin service. Optionally, you may also use the 'md5-password' attribute instead of 'password' for added security of user passwords.

By default, a database is configured to use the internal derby-based service. If a different service is required, an extra database element must be added to server.conf to tell the server which service to use for authentication.

The minimal file-based server.conf looks like:

<server xmlns='http://www.atomojo.org/Vocabulary/Admin/2007/1/0'>
<keystore password='atomojo' href='keystore'/>
<auth name="file-auth" class="org.atomojo.app.auth.FileAuthService" href="auth.xml"/>
<database name="data" auth="file-auth"/>
<interface address='*' port='8080' secure='true'/>
<host name='*' port='8080' database='data'/>
</server>

2.5 Multiple Databases

Atomojo can serve multiple different feed stores at once. All that is required to setup another database is:

1. add the database by name to db.conf
2. add a host element to server.conf

A database must be associated with a unique host name but a database may be shared amongst different host names.

2.6 Running a Daemon

Atomojo can use the Apache Commons jsvc program to run as a daemon on linux or other unix platforms supported by jsvc. This program allows the service to be started by root to bind to privileged ports and then switches to a regular user.

A sample script is provided in the jsvc directory as well as the source for building jsvc.

2.7 Queries

If you want query support, you must set the allow-queries attribute on host to true. This enables the /Q/ hierarchy.

2.8 Auto-configuration

Atomojo can be configured to read what databases, authentication services, and hosts it runs from an atom feed. Just insert the following element in the server.conf file:

<autoconf href="{uri}" username="{username}" password="{password}"/>

The uri can be relative to the configuration file. If the feed does not require authentication, the username and password attributes may be omitted.

An configuration feed must contain three kinds of entries:

• authentication
• database
• host

An authentication entry describes an authentication realm provided by the auth protocol (an auth service instance). Such an entry looks like:

<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Example Authentication Realm Entry</title>
<category scheme="http://www.atomojo.org/O/configuration/" term="realm"/>
<category scheme="http://www.atomojo.org/O/configuration/realm/" 
          term="name">myauth</category>
<link href="https://localhost:9080/realms/fc690197-1db1-4571-a207-4e6487792b03/" 
      rel="service"/>
</entry>

The categorization is required and the authentication service is named by the http://www.atomojo.org/O/configuration/realm/name term. The link with relation service points to the web service to use for authentication.

A database entry defines a database to be provided by the server and looks like:

<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Example Database Entry</title>
<category scheme="http://www.atomojo.org/O/configuration/" 
          term="db"/>
<category scheme="http://www.atomojo.org/O/configuration/db/" 
          term="auth">myauth</category>
<category scheme="http://www.atomojo.org/O/configuration/db/" term="name">mydb</category>
</entry>

The database is named by the http://www.atomojo.org/O/configuration/db/name term and must point to an authentication service (local or remote) via the http://www.atomojo.org/O/configuration/db/auth term.

Finally, a host can be configured by an entry that looks like:

<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Example Host Entry</title>
<category scheme="http://www.atomojo.org/O/configuration/host/" 
          term="name">myapp.somewhere.com</category>
<category scheme="http://www.atomojo.org/O/configuration/" 
          term="host"/>
<content type="text/xml">
<host xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0" 
      name="myapp.somewhere.com" database="mydb"/>
</content>
</entry>

The host entry contains an the host element as the entry's content. This is the exact host element that would normally be in the server.conf file. The host name should also be contain in the http://www.atomojo.org/O/configuration/host/name term.

The server reads this feed on a regular interval that defaults to 180 seconds. You can change that interval by specifying the number of seconds in the autoconf-check attribute on the server element of the server.conf file.

3. Admin Services

Atomojo servers are administered over HTTP via a set of REST-style XML web services or via an HTML interface. In the XML service layer, all the XML element names are in the namespace http://www.atomojo.org/Vocabulary/Admin/2007/1/0.

The base URI of the administration services is:

{host-path}/admin

Note: all XML documents are in the administration interface's namespace.

3.1 Users

The current set of users is represented by the resource URI:

{host-path}/admin/users

A GET request will return the current set of users represented by a users document element with a list of user elements--one for each configured users. No password information is returned via this service (or any other service).

A user is created by posting an XML document to this same resource URI with a document element of 'user' as follows:

<user xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"
      alias="{alias}"
      password="{password}"
  <name>{author name}</name>
</user>

The alias value is used for authentication and the author name value is used for the atom:author element's name.

Once a user has been created, it has a resource URI of:

{host-path}/admin/users/{alias}

A GET request will return an XML representation of the user (without any password information).

A DELETE request will delete the user.

A POST request of a 'user' document element with an updated password or name value will update the user. The alias cannot be changed via the service.

3.2 Synchronization

A synchronization process consists of a pair of a target local feed path and a remote app instance along with a synchronization method. Currently, there are two synchronization methods:

• Pull Synchronization where a set of feeds is pulled into the local store at the target
• Push Synchronization where changes to the target and its children are pushed to the remote app.

3.2.1 Local Synchronization Targets

The set of synchronization targets is available from the resource URI:

{host-path}/admin/sync/local

A GET request will return a XML document with a 'locals' document element. Each child 'target' element represents a different target. The 'name' attribute on each of these 'target' elements can be used to formulate the resource URI of the target:

{host-path}/admin/sync/local/{name}

A GET request on this URI will return an XML representation of the target of synchronization.

A DELETE request on this URI deletes the synchronization target and all synchronization processes associated with that target.

A new synchronization target can be created by posting an XML document to the resource URI of the set of synchronization targets (see above). This document must contain a single document element of 'target' as follows:

<target name="{name}" path="{feed-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

The 'feed-path' should be relative to the URI root feed of the store.

3.2.2 Remote APP Services

The set of remote APP services is available from

{host-path}/admin/sync/remote

A GET request will return a XML document with a 'remotes' document element. Each child 'app' element represents a different APP service. The 'name' attribute on each of these 'app' elements can be used to formulate the resource URI of the target:

{host-path}/admin/sync/remote/{name}

A GET request on this URI will return an XML representation of the target of synchronization.

A DELETE request on this URI deletes the remote APP service and all synchronization processes associated with that service.

A new remote APP service can be created by posting an XML document to the resource URI of the set of synchronization targets (see above). This document must contain a single document element of 'app' as follows:

<app name="{name}" introspect="{uri}" root="{uri}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<auth method="BASIC" name="{username} password="{password}"/>
</app>

3.2.3 Synchronization Processes

A synchronization process ties a local synchronization target to a remote application with a push or pull process. The set of process are available from:

{host-path}/admin/sync/process

A GET request will return a XML document with a 'processes' document element. Each child is either a 'push' or 'pull' element and represents a different sync process. The 'name' attribute on each of these elements can be used to formulate the resource URI of the target:

{host-path}/admin/sync/process/{name}

A GET request on this URI will return an XML representation of the target of synchronization process

A DELETE request on this URI deletes only the synchronization process.

A new synchronization process can be created by posting an XML document to the resource URI of the set of synchronization processes (see above). This document must contain a single document element of 'push' or 'pull' as follows:

<push name="{name}" target="{target-name}" remote="remote-app-name}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

<pull name="{name}" target="{target-name}" remote="remote-app-name}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

To invoke the synchronization process, make a GET request on:

{host-path}/admin/sync/process/{name}/start

3.3 Backup/Restore Services

Backup and restore services can be invoked via a simple XML post. To backup the whole database, just post the document:

<backup location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

to the resource:

{host-path}/admin/backup

This will create a copy of the database local to the system on which atomojo is running. At the root of the directory a document called _introspection_.xml is created that contains the service description of the backup according to the APP specification and similar to the service description your receive from the {host-path}/introspect resource.

You can restore from the filesystem as well. Just post a document like:

<restore location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

to the resource:

{host-path}/admin/restore

Unlike backup, an atomojo server can be restored from any APP service. Just post the XML document:

<restore xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<app name="{name}" introspect="{uri}" root="{uri}">
<auth method="BASIC" name="{username} password="{password}"/>
</app>
</restore>

to the resource:

{host-path}/admin/restore

This will restore the atomojo server by duplicating the remote APP service locally.

The use of the 'location' attribute is a shorthand for making the following request:

<restore xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<app name="restore" introspect="file:///{dir-path}/_introspect_.xml" root="file:///{dir-path}"/>
</restore>

Notice that since the content is stored locally, the service doesn't require an auth element.

3.4 Restart

If for some reason you want to restart a particular database without restarting the server you may do so by a GET request on:

{host-path}/admin/restart

4. Server Administration

Separate from the APP and Admin services, you can host a separate admin interface for administrating the server and all databases. This service is enabled by providing and authentication service and a definition of the admin host to the server.conf file.

First, you must configure an authentication service for the admin interface by adding a line like the following:

<auth name="admin-auth" class="org.atomojo.app.auth.FileAuthService" href="admin.xml"/>

Second, you need to define the admin host:

<admin name='*' port='8084' auth='admin-auth'/>

The name in the auth attribute must match a authentication service you have defined in the server.conf file. Also, you must make sure you add an interface element if you are going to host the admin interface on a different port.

Once you have the service defined, restart the server.

4.1 Listing Databases

You can list all the configure databases by a GET request on the resource:

{admin-url}/admin/database 

4.2 Backup of All Databases

A server may contain multiple databases statically and dynamically configured. All these databases can be backed up to a single location on disk by the resource:

{admin-url/admin/database/backup

A backup process is invoked by a POST of the following document:

<backup location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

where the dir-path is the location on disk to which the server will backup all the databases.

When the server creates the backup, it creates a separate directory named by the database name in that location for each database. You may restrict the databases that are in the backup by adding one or more a name child with the name of the database to backup.

For example, to limit the backup the 'A' and 'B' databases use the following request:

<backup location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<name>A</name>
<name>B</name>
</backup>

4.3 Restore of All Databases

Any database currently configured on the server can be restored by a request to:

{admin-url/admin/database/restore

A restore process is invoked by a POST of the following document:

<restore location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0"/>

where the dir-path is the location on disk to which the server will find the backup of the databases.

When the server performs the restore, it matches database names to the subdirectory names in the dir-path location. If the names match, a backup is expected to be in that directory and a restore is performed. You may restrict the databases that are in the restore by adding one or more a name child with the name of the database to restore.

For example, to limit the restore the 'A' database use the following request:

<restore location="{dir-path}" xmlns="http://www.atomojo.org/Vocabulary/Admin/2007/1/0">
<name>A</name>
</restore>

5.0 Alternate Storage

Atomojo supports a pluggable storage mechanism. The server ships with a file-based storage but other storage systems can be substituted when the server is started.

To change the storage, just add the --class parameter when starting the server to change the storage. For example, to switch to use the eXist XML DB:

server --class org.atomojo.app.storage.xmldb.XMLDBStorageFactory /opt/data

A storage mechanism implementation must implement the org.atomojo.app.StorageFactory interface.

5.1 XMLDB Storage

The implementation class org.atomojo.app.storage.xmldb.XMLDBStorageFactory provides the eXist-based XML storage. To use this storage you will have to augment the invocation scripts to include the atomojo-xmldb-storage.jar file and its associated libraries.