How to add a new realm

This document explains how to add a new realm to Yanel. We will explain this using the 'Yulup Editor' website as an example. From now on, we will refer to the directories that contain Yanel and the 'Yulup Editor' website as $YANEL_HOME and $YULUP_WEBSITE .

• Download the 'Yulup Editor' Website from Wyona's repository using git:

  git clone https://github.com/wyona/yulup.git
  

• Navigate to $YANEL_HOME and run

  ./build.sh add-realm -Drealm-config=$YULUP_WEBSITE/yanel/config/yanel-realm-config.xml -Drealm-mount-point=/yulup/ -Drealm-id=yulup
  

  Note: Usually the realm configuration file is named "realm.xml" and saved in the realm root directory.
  The 'Yulup Editor' website doesn't follow this convention, instead using a file named "yanel-realm-config" saved in "$YULUP_WEBSITE/yanel/config".
  If you name the realm configuration file conventionally as "realm.xml" you can point the "-Drealm-config=" parameter to the directory that contains the file.
  If you have a chosen a different name, please point that parameter explicitly to the file.

• Alternatively, you can add the realm node directly into $YANEL_HOME/conf/local/local.realms.xml. If you do not have this file, copy $YANEL_HOME/conf/realms.xml to $YANEL_HOME/conf/local/local.realms.xml first
  

  <realm id="yulup" mount-point="/yulup/" user-tracking-domain-id="boost-0123456789">
    <name>Yulup Editor Website</name>
    <config src="$YULUP_WEBSITE/yanel/config/yanel-realm-config.xml"/>
  </realm>

  NOTE for Windows users: Also use forward slashes, e.g.

  D:/realms/foo/yanel/config/yanel-realm-config.xml
  

• Rebuild Yanel
• Restart Yanel

Please note that the order of the realms doesn't matter. A request is dispatched to the realm with the longest matching mount-point.

Also note that IIRC the root attribute (see the welcome realm configuration) is used for inheritance. For example, if a realm does not specify a proxy configuration, it will inherit this configuration from the root realm.

The attribute 'user-tracking-domain-id' is optional and if not set, then the realm ID will be used instead. The attribute 'user-tracking-domain-id' is used for user tracking (see access log).

Some publicly available Third-Party realms

• 'Yulup Editor' Website
• 'Yulup Editor' Demo
• OSR-101 (Neutron Protocol Website)
• Yanel from Scratch Realm (U: anonymous, P: anonymous)

Developer Notes

If you want to modify the output of "./build.sh add-realm" you need to edit the Ant file where the "add-realm" target is defined:

$YANEL_HOME/src/build/targets/add-third-party-realm.xml

In that file you see the entry:

<target name="add-realm" description="Add third party realm" depends="init, build-add-realm-task">

This is where the target "add-realm is defined and configured. Inside this element there is another entry:"

<taskdef name="addrealm" classpath="${yanel.source.home}/build/classes" classname="org.wyona.yanel.ant.AddRealmTask">

The "classname" attribute defines the java class that will be executed for the "add-realm" target:

$YANEL_HOME/src/build/java/org/wyona/yanel/ant/AddRealmTask.java