Import/Create Site Directory

For demonstration purposes, we will build an example site for the Grey Dahut Preservation Initiative (GDPI). Sample content for that site is provided in the examples directory of the XIMS distribution in simple.examplesite.tld.

To build your site, you have two options to start with the SiteRoot content: First, you could create the content using the XIMS web user interface, second you can build the core content offline on disk and import it later using the fs_importer.pl tool. For our GDPI site, we will take the shortcut of importing the already existing files in the examples/simple.examplesite.tld directory. After cd'ing to the examples directory of your XIMS distribution, issue the following command:

Note: the script assumes that the password of the admin user is still the default password which is set after the XIMS installation. If you have changed that, you have to adapt the script.

[user@host examples]$ sh import_publish-simple.examplesite.tld.sh

This script will do the following:

  1. Import the simple.examplesite.tld directory under /root using fs_importer.pl

  2. Convert the imported folder to a SiteRoot and set its SiteRoot URL to http://simple.examplesite.tld using folder_to_objectroot.pl

  3. Add DepartmentLinks for index.html,about.html,team.html, and contact.html using add_departmentlinks.pl

If everything went right, you should see Successfully added Departmentlinks to '/simple.examplesite.tld' in your terminal and the imported site should be available at http://yourximshost.domain/goxims/content/simple.examplesite.tld

[ top ]

Create Role and User

Now, as we have got some content to work on, we need the users to get access to it. We will start out with creating a role for the Grey Dahut Preservation Initiative (GDPI) called GDPI.

Create role and assign it to parent role

Log in to XIMS as admin user and click on "Manage users and roles" at the "Administrative Options" section of your start page. At the "Create User" screen enter GDPI" as name of the user, "Grey Dahut Preserv. Initiative" as full name and set the "Account is an Abstract Role"-option to "yes". After the role has been created, click on "Grant Role" and grant it the role "everyone".

Assign default bookmark to role

After going back to the User/Role Management screen, click on "Bookmarks" for the newly created GDPI role. The path to the default bookmark is /simple.examplesite.tld in this case. Before clicking on create, do not forget to set the new bookmark as default bookmark.

The default bookmark will be inherited to all users of the GDPI role.

Create user and assign role

Back in the User/Role Management screen, we will create a user called bender for the president of the GDPI and grant it the GDPI role.

[ top ]

Set user metadata

You can move on to section Publish Site if you did not import your content using fs_importer.pl but created it using the web interface.

Because we have imported the contens of simple.examplesite.tld as admin, all the user medata of the objects points to the wrong person, as long as the admin is not the original author of course. In the case of the GDPI homepage president Bender himself is the author of the content. So, we want to update the imported XIMS objects accordingly, using the set_user_metada.pl tool in the admin subdir of the tools directory. After cd'ing to it, issue the following command:

[user@host admin]# ./set_user_metadata.pl -u admin -r -o bender -c bender -l bender /simple.examplesite.tld

This will set the owner, creator and last modifier of all 16 objects at /simple.examplesite.tld to the user bender. Note that set_user_metadata.pl requires XIMS admin privileges to run.

[ top ]

Assign Privileges

Now, as bender is the owner of the content, we may want to give him privileges to actually manage it. We could do that through the web user interface, however doing it recursively using the user_privileges.pl tool in the tools directory is less painful for your mouse finger:

[user@host tools]$ ./user_privileges.pl -u admin -r -l MODIFY,PUBLISH -g bender /simple.examplesite.tld

Note: MODIFY is a shortcut for the VIEW, WRITE, DELETE, ATTRIBUTES, TRANSLATE, CREATE, MOVE, LINK, ATTRIBUTES_ALL, DELETE_ALL, GRANT, GRANT_ALL, and OWNER privileges.

After granting to the user bender, we want to grant VIEW privileges to the GDPI role, to let other possible future grantees of GDPI see the content.

[user@host tools]$ ./user_privileges.pl -u admin -r -g GDPI /simple.examplesite.tld 

Later, Bender can manually grant other privileges besides VIEW to members of GDPI.

[ top ]

Publish Site

After you have created your initial content base, you may want to see how it will look like after it has been published. Per default, the XIMS config option ResolveRelToSiteRoots is set to '1'. As a consequence, all published XIMS internal references are created relative to the SiteRoot instead of being published relative to '/root'. For example, the link to the ObjectRoot settings file ou.xml created during export in the published version of index.html, like in every Document, will be set to '/ou.xml'. If ResolveRelToSiteRoots would be set to '0', the link to ou.xml would point to '/simple.examplesite.tld/ou.xml'. As ResolveRelToSiteRoots is set to '1' per default, you are expected to set up Apache virtual hosts for every site and direct the SiteRoot URLs to the according addresses.

Prepare publishing

During the development of your site's content, you surely want to already test and develop the navigation- and styling- elements of the site. To avoid adapting paths to stylesheets in the Apache AxKit server configuration and to avoid adapting paths inside your stylesheets, which would have to be changed from /ximspubroot/simple.examplesite.tld/stylesheets/default.css to http://simple.examplesite.tld/stylesheets/default.css for example, you have the option to locally use the future live SiteRoot URL or a temporary staging URL.

Scenario 1: simple.examplesite.tld is already running on a different server or is not running anywhere yet.

In that case you can locally set up a DNS entry for simple.examplesite.tld to get access to it. On Unix flavor systems you have to adapt the /etc/hosts file as superuser for that, on Win32 boxes, the file can be found at %SystemRoot%\%Windir%\system32\drivers\etc\hosts (e.g.: C:\WINDOWS\system32\drivers\etc\hosts). Add an entry in the form of "ip-address hostname", "138.232.10.18 simple.examplesite.tld" for example. After your local workstation knows where to look for simple.examplesite.tld, you have to tell your Apache server what to do if a browser requests simple.examplesite.tld. You have to add the configuration for the virtual server similar as described in Managing Multiple Sites with XIMS:

<VirtualHost *>
    ServerName simple.examplesite.tld
    DocumentRoot /www/ximspubroot/simple.examplesite.tld
    Include conf/simple.examplesite.tld.axkit-conf
</VirtualHost>

Note: You can use the sample Apache config provided in the examples directory of your XIMS installation for that. Just add the line "Include /usr/local/xims/examples/simple.examplesite.tld-httpd.conf" in your httpd.conf.

Scenario 2: simple.examplesite.tld is already running and it runs on the same server

In that case, you may set up a temporary staging address for your site. You can do that locally in your hosts file as described above, or register the staging URL at a DNS server. You still have to configure the virtual host in your Apache server configuration. For example:

<VirtualHost *>
    ServerName staging.examplesite.tld
    DocumentRoot /www/ximspubroot/simple.examplesite.tld
    Include conf/simple.examplesite.tld.axkit-conf
</VirtualHost>

To point the users to the correct URL of the staging server, you have to change the SiteRoot URL accordingly. The SiteRool URL http://simple.examplesite.tld, set by import_publish-simple.examplesite.tld.sh, must be changed to http://staging.examplesite.tld in our example.

Update Apache Axkit configuration

As you mave have noticed, a file conf/simple.examplesite.tld.axkit-conf is referenced in the above Apache config examples. This file configures AxKit to use the stylesheet /stylesheets/default.xsl for all *.html files. The config could look like the following:

Note: If you included /usr/local/xims/examples/simple.examplesite.tld-httpd.conf as described in the note above, AxKit will already use /usr/local/xims/examples/simple.examplesite.tld-axkit.conf and you do not need to create an extra conf/simple.examplesite.tld.axkit-conf.

<Files *.html>
    SetHandler axkit
    AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
    AxErrorStylesheet text/xsl /stylesheets/error.xsl
    AxAddPlugin Apache::AxKit::Plugin::Passthru
    AxAddPlugin Apache::AxKit::Plugin::AddXSLParams::Request
    PerlSetVar AxAddXSLParamGroups "Request-Common HTTPHeaders VerboseURI"
    AxAddProcessor text/xsl /stylesheets/default.xsl
</Files>

Publish Objects

Now, as URLs, Apache, and AxKit are configured, you can start to publish your content objects. You can do that either by using the web interface or by publishing all at once using the publisher.pl tool in the tools directory:

Warning: If publisher.pl does not have the setuid flag set, you can only use publisher.pl as superuser or as an user with write access to the ximspubroot directory respectively!

[user@host tools]$ ./publisher.pl -u admin -r /simple.examplesite.tld

To have the expected results regarding the use of the DepartmentLinks portlet, we have to republish the SiteRoot. This will add the link to the - by now published - portlet in ou.xml:

[user@host tools]$ ./publisher.pl -u admin /simple.examplesite.tld

If you followed the example config so far and everything has worked, you will see the following index page:

Go Live

From the administrative point of view, there is little to do to go live now. With the above mentioned scenario 1, the only thing to do is to change the DNS entry for the old simple.examplesite.tld to point to the new XIMS powered host. If you have a set up similar to the one described in scenario 2, you have to change two things to go live: First, adapt the name of the virtual host in the Apache config to the name of the final production server, simple.examplesite.tld in our example. And second, update the SiteRoot URL inside XIMS accordingly. In our example, that would mean changing http://staging.examplesite.tld back to http://simple.examplesite.tld again by editing /simple.examplesite.tld.

[ top ]