Sunday, April 19, 2009

How to build ORYX editor in Ubuntu


Oryx editor is a web based BPMN (Business Process Modeling Notation) editor. Oryx is a project of the Business Process Technology research group at the Hasso Plattner Institute of IT Systems Engineering at the University of Potsdam, Germany. The research group is led by Professor Mathias Weske, as is the Oryx project.
This blog is focused on building Oryx from the source in Ubuntu.

RequirementsJ2SE 5 Java Runtime Environment or higher
SubVersionApache Tomcat server (5.5 or higher)
Apache Ant 1.6 or higher
Checkout the sourceFirst you have to check out the source from the SubVersion repository

svn checkout oryx-editor-read-only

After checking out the source you have to build the source using Ant. But before that you need to configure the database server which used to store the Oryx business process models. Here I have described on configuring the PostgreSQL database server.

Configure the PostgreSQL database 1.Install PostgreSQL sudo apt-get install postgresql-8.3 postgresql-plpython-8.3

2.Then we have to configure the database such that it does not require passwords for local tcp connections. Before that if the database server is started you have to stop it using the following command.
/etc/init.d/postgresql-8.3 stop
3.For that client authentication configurations for the database have to be changed. Traditionally these configurations are stored in pg_hba.conf file located at /etc/postgresql/8.3/main.

Modify the configurations as follows.

# Database administrative login by UNIX sockets
local all postgres ident sameuser


# "local" is for Unix domain socket connections only
local all all trust
# IPv4 local connections:
host all all trust
# IPv6 local connections:
host all all ::1/128 md5

4.Then start the database using the following command
/etc/init.d/postgresql-8.3 start

5.Now using the following commands you have to create a user called “poem” without password.
su postgres
createuser --superuser --echo poem

Now PostgreSQL database configuration process is completed such that there is user called “poem” which can connect to the database without passwords and database server trusts all the tcp local connections. Now all the requirements for the building process are completed.

Building the source

Before building the source you need to modify the configuration file located at the root of Oryx source. You need to change “deploymentdir” in to the full path to the tomcat deployment directory.
eg. deploymentdir = /opt/installations/tomcat1/apache-tomcat-6.0.18/webapps
If you go into the root of Oryx source directory you may see a dependency graph (build-dependencies.png) which depicts on how the Ant targets are inter-dependent.

Now using the following command the Oryx source can be build.
ant rebuild-all
Like wise using the ant targets you can compile, clean, build, deploy Oryx.

As well you have to create the database which stores the Oryx business process models using the following commands.
/etc/init.d/postgresql-8.3 start
ant create-db
In this case if you have configured the PostgreSQL database server correctly, no password will be asked during the database creation and the database will be created without an error.

Then to deploy the Oryx editor use the following commands.
ant deploy-all
Now if you go in to the tomcat deployment directory you may see two WAR distributions called backend.war and oryx.war. Extract both of them. Now by starting the tomcat engine you can deploy the Oryx editor.

Finally you can open the Oryx model repository in Firefox3.


olha said...

Your how-to was a good basis for installing ORYX locally on a MAC OS Leopard... Thank you for that.
I also run a WSO2 Identity Server locally, I thought it was a good idea to the identity server in order to login in the locally installed ORYX. But unfortunately the Identity server doesn't go back to the ORYX after having signed in. Do you have an idea?

Denis Weerasiri said...

@olha, Are you using v 2.0.1?.

olha said...

Yes, I am using the identity server 2.0.1.

DaKaiman said...

how con i use WsO2 Identity Server in Oryx?


Denis Weerasiri said...

Hi @Kai,
Can you please check the oryx mailing list. .
I'm not into oryx code right now. But please take a look at poem-jvm/src/java/org/b3mn/
It might help.

Joshua said...

Hallo Denis

I have installed Oryx succesfully but don't see BPMN 2.0 nor BPMN 1.2
types in Type Filter section.

Thanks in advance.

emma said...


has anyone intalled Oryx on Windows?I have some trouble with the part "Load Database Schema¶
Manually" from the description website:

The last command: psql -U postgres --dbname poem --file db_schema.sql
gives lots of errors back. Where should I be possitioned in order to execute the command?

thanks in advance

carza said...

I am working on Open Jdk, tomcat 6, postgresql-8.4 environment,and i have followed the exact steps Denis prescribed but i have encountered the following error on my web page

type Exception report


description The server encountered an internal error () that prevented it from fulfilling this request.


javax.servlet.ServletException: java.lang.NullPointerException

root cause


note The full stack trace of the root cause is available in the Apache Tomcat/6.0.24 logs.

peter0601 said...

Hi carza,

I have pretty much the same problem as you. Did you ever solved it and got it to work?

Cheers Peter

peter0601 said...

Hi there,

I solved the problem described by carza.

The problem is, that the poem user in the postgres db doesn't have a password set. Set a password and try again.

After that it worked for me!!!

Don't forget to change the openId, if you don't want to use your own, to OryxUser in class


fodnaz said...

Thanks for this guide.

I have followed the guide, I have built the source using Eclipse EDI and the ant command. in both ways I got the same issue. in the backend directory i didn't find any "Poem" directory. however I found a "repository2" directory under the dist directory.

I launched the Oryx editor using the url
localhost/oryx/editor. But I was not able to save, i have got error "you have no right to save". I checked rthe code and found lot of references to the directory /backend/poem/

Note. i have loaded the code from:

Can any one help on this

Thank you in advance

yatalkintome? said...

Hey man, good post. Very useful.
Do you have something that explain the basic working of oryx? I'm having a bad time going through all the javascript code.

Selvakumar said...

Hi Peter

I'm also getting the same exception as explained by carza.

Can you please explain what we need to change regarding openId?

Can you please send me the file?

Thank You

Paul said...

Hello Denis,

Thank you for your great contributions and information about Oryx editor. Since Oryx is a web-based, I would like to know if it can be accessed from iPad via the safari browser. Actually, I am looking for a computational workflow editor that can be used on both iPad and desktop.
Thank you very much for your response.