Basic instructions for installing Akara, primarily for Linux/BSD-like systems
You might find more specific/detailed recipes for your situation.
Contents
Installation
Setting up a user virtual Python environment
Set up Virtualenv` with distribute.
Download virtualenv.py, then install it:
mkdir -p ~/.local/venv/main python virtualenv.py --distribute --unzip-setuptools $HOME/.local/venv/main
This also installs pip
Setting up the environment
Run the following once and also add it to `~/.bashrc`:
[uche@web21 ~]$ source $HOME/.local/venv/main/bin/activate (.local)[uche@web21 ~]$
This will make sure the virtual Python executable comes before the main system-wide one.
Installing Amara and Akara
pip install -i http://pypi.zepheira.com/releases/index Amara pip install -i http://pypi.zepheira.com/releases/index Akara
Prep the Akara config
Download the sample config
wget https://raw.github.com/zepheira/akara/master/lib/akara.conf mkdir $HOME/.config/ mkdir -p $HOME/.local/venv/main/akara/logs mkdir -p $HOME/.local/venv/main/akara/modules cp akara.conf $HOME/.config/
Edit the ConfigRoot line within akara.conf so that it looks like:
ConfigRoot = "~/.local/venv/main/akara"
Start the Akara server:
akara start
If you get any errors, check the log at ~/.local/venv/main/akara/logs/error.log. You might need to tweak the config at ~/.local/.config/akara.conf
You can check its basic workings with the built-in echo service
$ curl --request POST --data-binary "Hello, world" http://localhost:8880/akara.echo
Which should print "Hello, world" on the command line.
Getting started with Akara
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 tried out the echo module, which is useful in some debugging scenarios, but not very exciting.
Edit the config file (e.g. $HOME/.config/akara.conf) to add in any modules you'd like to try out. For example, to create an XSLT Web service, update the MODULES list along the following lines:
MODULES = [
"akara.demo.echo",
"akara.demo.xslt",
]Each of the list entries is a module from your $PYTHONPATH. Restart akara:
akara restart
Again you can watch the error log ( $HOME/.local/venv/main/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://github.com/zepheira/amara/raw/master/demo/data/identity.xslt"
Replace '@foo.xml' with any local XML file.
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/
<?xml version="1.0" encoding="utf-8"?>
<services><service ident="http://purl.org/xml3k/akara/services/registry"><path template="http://localhost:8880/?service={service?}"></path><description></description></service><service ident="http://purl.org/xml3k/akara/services/demo/echo"><path>akara.echo</path><description>Sample request:
curl --request POST --data-binary "@foo.dat" --header "Content-type: text/plain" "http://localhost:8880/akara.echo"</description></service><service ident="http://purl.org/akara/services/demo/xpath"><path>akara.xpath</path><description>select - XPath expression to be evaluated against the document
tidy - 'yes' to tidy HTML, or 'no'
Sample request:
curl --request POST --data-binary "@foo.xml" --header "Content-Type: application/xml" "http://localhost:8880/akara.xpath?select=/html/head/title&tidy=yes"</description></service><service ident="http://purl.org/akara/services/demo/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></services>Three services are listed in the resulting XML. One is the discovery service itself (at top level), and the other two are the echo and xslt service enabled in the configuration.
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 the xslt service. Add to the akara.conf a section at the bottom as follows (I auggest after the marker "Section 3: Other module configuration goes here"):
class xslt: #Corresponding to the module filename, xslt.py
default_transform = "http://github.com/zepheira/amara/raw/master/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/venv/main/akara/logs/error.log' Access log file: '/Users/uche/.local/venv/main/akara/logs/access.log' PID file: '/Users/uche/.local/venv/main/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