Amun manual

GPLv3

Abstract

This is the offical manual of Amun.


Table of Contents

1. Introduction
2. Installation and Configuration
2.1. Requirements
2.2. Prepare
2.2.1. Setting rights
2.2.2. Edit config
2.2.3. Change salt
2.3. Run installer
2.4. Clean up
3. Connect to the Amun API
3.1. Configuration
3.2. OAuth authentication
3.3. Working with Zubat
4. Service
4.1. API
4.2. Application
4.3. Gadget
5. Advanced topics
5.1. Connect hosts
5.2. Approval
5.3. Notifications
6. 3rd party applications
7. Help

Chapter 1. Introduction

Amun is a content managment framework written in PHP 5 and based on the PSX framework. The goal of Amun is to build a more federated and programmable web. This is achieved by providing an RESTful API for managing and distributing the content in standard formats like JSON, XML, Atom and RSS.

Chapter 2. Installation and Configuration

This chapter describes howto install and configure Amun properly.

2.1. Requirements

You need PHP >= 5.3 and a MYSQL database.

2.2. Prepare

The installation is done via an install script but before you can start it you have to make the following changes.

2.2.1. Setting rights

Amun needs in the following locations read write and delete permissions. In "library/Amun/Service", "template/default/application/", "module/application" and "module/gadget" these are the locations where the service installer copies the files (from the service folder) and deletes it on uninstalling. You should set also write permission to the location "cache/".

2.2.2. Edit config

First open the file configuration.php with you favorite editor. The config is an simple associative array with [key] > [value] pairs. Goto the key "psx_url" and change the value to your domain. Note do not use a trailing slash. Goto the "sql_*" keys and enter your connection datas.

2.2.3. Change salt

Amun uses a salt to store user passwords and identities. Because the install script creates a new administrator user you must define the salt before you install them. Open the file library/Amun/Security.php and change in the method getSalt() the variable $salt to something different.

2.3. Run installer

Now you can point your browser to http://[server]/[path]/public/index.php/install and run the install script. Enter all your data and click on install. Note the install script is javascript based so you need enabled javascript. If the installation was succesful you can goto the main page and login with your admin account. In order to configure the website you have to install a backend. The next chapter describes howto use "Zubat" wich is a backend written in java.

2.4. Clean up

It is highly recommended that you delete the files wich are used by the install script.

Files that are used by the installation

  1. module/install.php

  2. template/default/system/install.tpl

Chapter 3. Connect to the Amun API

In order to configure Amun you need a backend to connect to the API. In this case we use Zubat. Goto the project page and download the current version of Zubat. You can find a list of available backends at the website.

3.1. Configuration

Before you start Zubat you have to enter the consumerKey and consumerSecret to the config. The consumerKey and consumerSecret was sent to your email address wich you have provided on installation. If you dont have received this email you can get the consumerKey and consumerSecret from the table "amun_system_api".

3.2. OAuth authentication

In order to connect to Amun we have to obtain an OAuth token and token secret. We do this by starting Zubat with the following command:

java -jar zubat.jar --auth

Click on the "Login" button to start the authentication process. If the application was approved you have to provide the verification code to Zubat. On success Zubat tries to write the token and token secret to the config xml so make sure that it has write access.

3.3. Working with Zubat

If the authentication was successful you can start Zubat with the following command:

java -jar zubat.jar

With Zubat you can basically INSERT, UPDATE and DELETE records of Amun. As mentioned Zubat is for developing and debugging Amun therefore it is not intended for endusers but can be used to start working with Amun.

Chapter 4. Service

In amun every functionality is provided via a service. All services are normally placed in the folder "service" but the location can be defined in the configuration at the point "amun_service_path". On Installation some basic services are installed but you can install and uninstall every service later on. If a service is installed the files from the service are copied into the specific library, module and template folder location. An service can add functionality to the following sections.

4.1. API

Every service wich insert, update or delete data defines an RESTful API endpoint designed after the OpenSocial Core API specification. The endpoint is normally at the following location:

http://[url]/index.php/api/service/[service]

4.2. Application

The application represents the functionality of the website. In general it offers a user interface to use the API.

4.3. Gadget

A gadgets is a small script wich can be loaded beside an application to display additional informations.

Chapter 5. Advanced topics

...

5.1. Connect hosts

It is possible to connect amun instances into a network. This has the advantage that users within a network dont have to create an account for each website instead they can use an existing account. It is also possible to add every user in the network as friend.

5.2. Approval

In order to use the approval system you have to add a record to the system approval table. I.e. if you want that comments on the page id 5 should be approved before inserting you have to add the following data:

Table: amun_service_comment
Field: pageId
Value: 5

That means if an record is inserted into the table "amun_service_comment" and this record has a field "pageId" with the value "5" then the record is added to the approval queue. Then you can either update or delete the record.

5.3. Notifications

The table amun_system_notify contains a list wich class gets notified if a record is inserted, updated or deleted for the specific table. Amun uses Stomp to notify other applications about events. Your stomp client has to subscribe to /queue/amun at the broker. I.e. if you want send a message to all listeners if a news is inserted you have to add the following data:

Priority: 0
Table: amun_service_news
Class: Amun_Notify_Stomp

The news is submitted JSON encoded to all subscribers. In this way you can delegate time consuming tasks like sending bulk mails, notifing users per XMPP or generating pdfs to other applications. Also almost every programming language has an stomp client library.

Chapter 6. 3rd party applications

Amun uses some 3rd party libraries and applications. Thx to all the developers for making such great software!

A list of all 3rd party applications used by Amun in alphabetical order.

  1. Ace: http://ace.ajax.org/

  2. Blueprint CSS Framework: http://blueprintcss.org

  3. HTMLPurifier: http://htmlpurifier.org

  4. jQuery: http://jquery.com

  5. PSX: http://phpsx.org

Chapter 7. Help

Amun is currently in an early stage so the documentation is very sparse. If you need help you have the followign options.

Things you can do if you have any problems with Amun

  1. Write an email to the mailinglist

  2. Join the IRC channel #phpsx on freenode

  3. Write an issue to the bugtracker