THIS PAGE IS DEPRECATED. PLEASE USE Akara/Install

Notes for getting started with Akara, particularly for development and experimentation. For proper, system configuration, and platform-specific notes, see Akara/Install.

Installing the prerequisite

First install Amara 2.x: Amara/Install. Many of the installation recipes on this wiki cover both Amara and Akara.

Installing Akara

Install Akara from a nightly snapshot (assumes you have pip):

pip install http://files.akara.info/00-akara-latest.tar.bz2

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

pip install -e hg+http://bitbucket.org/uche/akara#egg=akara

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 the PATH and PYTHONPATH environment variables.

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.

#(!) Akara is a well-behaved UNIX process. For example you can kill -HUP it to reload modules. The pid will be, by default, at $HOME/.local/lib/akara/logs/akara.pid

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"

A few tips for working with the server

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

To rotate the logs, use

$ akara rotate

You might see fit to rotate the logs each time you restart the server, or to Probably a good idea to rotate the log before restarting:

akara rotate akara restart

The logs can get big, especially if you're

What's next

To try out more of the demo modules, see README in the demo/modules directory

To get started writing your own modules, see Akara/Tutorial

#
#