What does CXAN contain?

CXAN offers a variety of packages, from simple tool libraries to entire web
applications. It is based on the EXPath packaging system. The package format
supports technologies such as XQuery, Javascript, XSLT, RDF, XML Schema, SPARQL,
and more.

Each package has its own package page on the website, containing more
information about it. The website can be searched for packages, or simply
browsed.

Where is the REST API?

You can access CXAN information using a read-only REST-like API.
Just use the same URLs as for the website, but add the HTTP header
Accept: application/xml. You will get back a simple XML
representation of the information shown on the corresponding webpage.

Who maintain packages?

The packages on CXAN are maintained by a community of volunteers. Each package
is assigned to one maintainer. Each package page contains more information about
its maintainer.

How are packages maintained?

Technically, packages are maintained in Git repositories. CXAN monitors some
specific repositories. Each maintainer has his/her own repository, containing all
the packages he/she maintains. Each Git repository has a specific structure,
defined by CXAN (basically containing packages in a specific directory structure,
based on conventions, besides a few config informations kept in a couple of XML
files).

Maintainers simply maintain the packages they are responsible for in their own
Git repository, using all the Git tools they want. As soon as they push changes to
the remote repository (well, as soon as CXAN pull these changes), like adding a
new version of an existing package, the change becomes available on the CXAN
website.

Why using Git?

By using Git, there is no need to implement a security mechanism, or a form to
upload new packages. Maintainers can use all Git tools, as they are used to,
possibly entire teams collaborating, or using several branches to map their
development and release process, as they do for any other piece of
software.

By using Git, having a copy of each repository on (at the very least) the
remote host, the maintainer local machine and the CXAN website, effectively
creates as much backup of each repository on different locations, and maintained
and backed up each by different persons or companies or organizations. The updates
are transmitted by following the chain of Git pushes. The risk of loosing anything
is very low (virtually inexistant), without even having to write any backup
strategy.

GitHub does not allow binaries!

CXAN does not use GitHub (except for its own source code). It uses Git. If a
maintainer wants to use GitHub, that is its responsibility (I do not think that a
couple of small packages, typically less than 100 Ko, is a real problem). I
personally use my own server of remote Git repositories.

How can I add a new package to CXAN?

Either you contact a maintainer and convince him/her to add your package (e.g.
if the package is related to the maintainer activity). Or you volunteer to become
a maintainer yourself. In that case the first step is to create a remote Git
repository with the format CXAN expects. Then contact Florent Georges on the EXPath mailing list (or in private if you
don't want to write to the mailing list for whatever reason) in order to add your
repository to CXAN.

What is the structure of a CXAN repository?

The format is quite simple. If you prefer to learn by example, you can have a
look at Florent's personnal repository,
or at the EXPath repository.

The root directory must contain a file called packages.xml, with
the following format (there must be one element pkg for each package
in the repository):

How do I install a local CXAN?

You can install your own CXAN locally, either to deploy your own local system,
or as a package repository maintainer, to double-check your packages before
pushing them to http://cxan.org/. In a nutshell, you need to install the
following:

First, create a directory which will contain your installation. It will contain
Servlex as a sub-directpry, another one will be its application repository, yet
another one will be the Git base for the package repositories, and so on. Let us
call that directory cxan.home.

To install Servlex, just go to http://servlex.net/, and follow the instructions. The easiest way is to
download the installer, and execute it (that is a JAR file, either with a
graphical installer, or text-based if your system is text-only). Adapt the
directory to cxan.home/servlex. Once it is installed, move the
directory cxan.home/servlex/repo to cxan.home/repo
and adapt the value of org.expath.servlex.repo.dir accordingly in
cxan.home/servlex/conf/catalina.properties.

Adapt the port 19757 to the port number you want to use, in
cxan.home/servlex/conf/server.xml. Now you can start Servlex by
executing cxan.home/servlex/bin/startup.sh (you might need to set the
exec bit on the shell scripts first: chmod u+x *.sh). Go to the
Servlex Manager on http://localhost:19757/manager/ (adapt the port number if you changed
it in Servlex configuration) to validate it has been installed correctly.

Go to the "Deploy" page of the Servlex Manager, and write down
fgeorges/fxsl in the CXAN ID field. Press "Deploy" in order to
install the first dependency of the CXAN website application directly from CXAN
itself. Confirm the installation. Then go back to the "Deploy' page and repeat
this process for the packages fgeorges/pipx,
fgeorges/serial and finally the CXAN Website itself:
fgeorges/cxan-website. But before testing it, we need to create
the Git base directory.

Create the directory cxan.home/git-base/master/. Copy the file
cxan.home/repo/cxan-website-0.7.0/content/config-params.xml to
cxan.home/repo/config-params.xml, and edit the value of the
git-base parameter (make sure that all references to
config-params.xml in
cxan.home/repo/cxan-website-0.7.0/content/data-access/dir-repos.xpl
are pointing to the file (they should all be exactly
../../../../config-params.xml). The value must be an absolute path
on your system, starting with file:/, and pointing to the directory
cxan.home/git-base/master/ you have just created. Create the file
cxan.home/git-base/master/repositories.xml with the following
content:

Adapt the values to the package repositories you want to add to your own CXAN
deployment, and create a new element repo well, for each such repo.
Do not forget to actually clone each of the repositories at the given
place.

Create both directpries cxan.home/git-base/master/sanity/ and
cxan.home/git-base/master/authors/. And create the file
cxan.home/git-base/master/authors.xml with the following content
(adapt the content, all author codes in your repositories must exist in this
file):

Now, the last step is to download the CXAN tools. Create the directory
cxan.home/tools/, and unzip there the content of the latest file
cxan-website-tools-*.zip that you can find on the CXAN page of the
CXAN website
package. You can then invoke the shell script, with the git-base directory as an
option (use an absolute path): ./update-repos.sh
cxan.hom/git-base.