This page covers detailed, proper system configuration, and platform-specific notes, if you just want to get started experimenting or developing with Akara, see Akara/Quick_start.

Installing the prerequisite

You need Python 2.5 or 2.6. Python 2.7 should work, but not yet 3.x. You also need to install Amara 2.x: Amara2/Install.

Installing Akara on Linux

Install Akara from a nightly snapshot:

cd $HOME/dl
wget http://files.akara.info/00-akara-latest.tar.bz2
cd $HOME/src
tar jxvf $HOME/dl/00-akara-latest.tar.bz2
cd akara
python setup.py install

• If you prefer pulling trunk from Mercurial, you can pull from: http://bitbucket.org/uche/akara/ or http://hg.xml3k.org/akara (browser)

Now prep the Akara config:

mkdir $HOME/.config/
mkdir -p $HOME/.local/lib/akara/logs
mkdir -p $HOME/.local/lib/akara/modules
cp lib/akara.conf $HOME/.config/
#Copy a module for testing
cp demo/modules/echo.py $HOME/.local/lib/akara/modules

You may need to update PATH and PYTHONPATH, e.g. by adding (on Linux) the following to the ~/.profile (and running it on the command line for the first time)

export PATH=$PATH:~/.local/bin
export PYTHONPATH=$PYTHONPATH:~/.local/lib/python 

Start the Akara server:

akara start

If you get any errors, check the log at ~/.local/lib/akara/logs/error.log. You might need to tweak the config at ~/.local/.config/akara.conf

Trying out some modules

Akara works with modules that you can install for data processing and transforms. These modules contain one or more RESTful end-points. A few modules come included as demos, showing you the way to build and install your own Akara modules. In the section above you installed the echo module, which is useful in some debugging scenarios, but not very exciting.

Copy over the modules you'd like to try out. For example, to create an XSLT Web service:

cp $HOME/src/akara*/xslt.py $HOME/.local/lib/akara/modules

Restart akara

akara restart

Again you can watch the error log ( $HOME/.local/lib/akara/logs/error.log ) for any sign of problems.

And just like that you have an XSLT Web service. Try it out!

curl --request POST --data-binary "@foo.xml" --header "Content-Type: application/xml" "http://localhost:8880/akara.xslt?@xslt=http://hg.akara.info/amara/trunk/raw-file/tip/demo/data/identity.xslt"

Replace '@foo.xml' with any local XML file. Replace the xslt= parameter with any XSLT file available on the Web.

Discovery

Akara has a mechanism for reporting what services are available, mounted on an instance. By default this comes as an XML file served by a GET of the root of the Akara instance. For example, after you've set up Akara on localhost, and you've copied over the xslt.py module, you should get:

$ curl "http://localhost:8880/"
<service name="_list_services">
  <path></path>
  <description>None</description>
</service>
<service name="akara_xslt">
  <path>akara.xslt</path>
  <description>
    @xslt - URL to the XSLT transform to be applied
    all other query parameters are passed ot the XSLT processor as top-level params
    
    Sample request:
    curl --request POST --data-binary "@foo.xml" --header "Content-Type: application/xml" "http://localhost:8880/akara.xslt?@xslt=http://hg.akara.info/amara/trunk/raw-file/tip/demo/data/identity.xslt"
    </description>
</service>

Two services are listed in the resulting XML. One is the discovery service itself (at top level), and the other is the akara.xslt service in the xslt.py module.

Of course there are security implications to discovery. Akara does not presently provide any concessions to deal with this. For now the simple rule is: don't mount any services within Akara unless it's OK for anyone else to know it's there.

Notes on configuration

You'll want to provide particular configuration for some services (some config might even be mandatory for some services).

For example, you can configure a default transform for xslt.py. Add to the akara.conf a section at the bottom as follows:

[xslt] #Corresponding to the module file, xslt.py
default_transform=http://hg.akara.info/amara/trunk/raw-file/tip/demo/data/pretty.xslt

Now you can invoke the service as above, but with the XSLT parameter omitted from the URL, and it will use the configured default:

curl --request POST --data-binary "@foo.xml" --header "Content-Type: application/xml" "http://localhost:8880/akara.xslt"

Checking server state

To check the state of the akara server, run akara status e.g.

$ akara status
  == Akara status ==
Configuration file: '/Users/uche/.config/akara.conf'
Error log file: '/Users/uche/.local/lib/akara/logs/error.log'
Access log file: '/Users/uche/.local/lib/akara/logs/access.log'
PID file: '/Users/uche/.local/lib/akara/logs/akara.pid'
PID is 707 and there is a process with that PID
Akara is running