Installation

Last reviewed: 01-Dec-2024

(*** See an error, omission, obsolete information below? Let us know by opening a new issue report with one click. Thanks! ***)

The Standards Information System is built upon XML technologies. The data are represented in XML and stored in an XML database -- eXist-db, which can be downloaded from the eXist-db home page. As of Autumn 2024, the SIS uses eXist-db version 6.3.0.

Please note: since the early 2023, there is an annoying (but in fact little) installation bug, with some leads described in our ticket https://github.com/clarin-eric/standards/issues/214 -- the overall message is: if you feel like doing a tiny amount of tinkering, go for the current release of eXist 6.x and follow the hints in the bug report on what to fix by hand. Otherwise, use an earlier stable version of eXist, SIS should run on that without a problem (for some time to come).

Please follow the instructions below in order to get the SIS running on your computer. These instructions are meant primarily for those who would like to participate hands-on in developing the system, for example by updating information on standards, adding format specifications, but also by suggesting better ways to visualize some of the resulting data combinations. It may also be useful for those colleagues who are preparing for Inputhons at their centres and wish to test their new recommendations locally on their machines.

1. Install eXist-db 6.x according to the instructions in the eXist documentation. Note that you will be asked to create an admin password. Do make a note of it.

2. It is a good idea to start eXist for the first time in the GUI mode (via a shortcut), because then it is going to detect the first run and ask you additional configuration questions. When that happens, you may want to set the Jetty HTTP port to 8889, as shown in the bottom of the screenshot:

   Upon saving, you will be asked about whether it's OK with you that the data/ directory is not empty. Just hit "OK" to move on and then wait for the splash screen that will update you on what is being installed.

NOTE 1: you may just go with the default port, 8080. The trouble with it is that it is default for many applications, and you might create a conflict. On the other hand, by not modifying the default port, you will avoid the small tinkering issue that the issues mentioned above provide workarounds for.

NOTE 2: above, the SSL port is also modified (instead of the default 8443, you can see 8444). We used to need that port for direct logins with the online instance, but have disabled that option. It might come back, though, so we still mention the SSL port in the installation notes.

NOTE 3: a quick way to go about the installation is: (a) used the eXist-db installer to set the admin passwd, (b) modify the etc/jetty/jetty-http.xml (and jetty-ssl.xml) files by hand, by changing the default values from 8080 to 8889 and from 8443 to 8444, respectively, and (3) by running /bin/startup.sh and waiting a bit while the database configures itself for the first time.

3. In many cases, you will run eXist from a desktop shortcut (or Start menu) of your system. In some cases (e.g. under Ubuntu), it seems less troublesome to run it from the command line. In order to do that, execute:

   ./{eXist-db-installation-folder}/bin/startup.sh

(naturally, it may be easier to first switch to the directory ./{eXist-db-installation-folder}/bin/ and then run ./startup.sh, but we'll keep to the convention above in what follows)

Under Linux and when running startup.sh in a terminal, you should see a number of reports ending with something like the following:

11 Mar 2021 01:15:32,017 [main] INFO  (JettyStart.java [run]:285) - ----------------------------------------------------- 
11 Mar 2021 01:15:32,017 [main] INFO  (JettyStart.java [run]:286) - Server has started, listening on: 
11 Mar 2021 01:15:32,017 [main] INFO  (JettyStart.java [run]:288) - 	http://127.0.1.1:8889/ 
11 Mar 2021 01:15:32,018 [main] INFO  (JettyStart.java [run]:288) - 	https://127.0.1.1:8444/ 
11 Mar 2021 01:15:32,018 [main] INFO  (JettyStart.java [run]:291) - Configured contexts: 
11 Mar 2021 01:15:32,018 [main] INFO  (JettyStart.java [run]:297) - 	/ 
11 Mar 2021 01:15:32,019 [main] INFO  (JettyStart.java [run]:312) - '/iprange' 
11 Mar 2021 01:15:32,020 [main] INFO  (JettyStart.java [run]:297) - 	/exist 
11 Mar 2021 01:15:32,020 [main] INFO  (JettyStart.java [run]:312) - '/exist/iprange' 
11 Mar 2021 01:15:32,021 [main] INFO  (JettyStart.java [run]:318) - ----------------------------------------------------- 

From this point on, you can continue either leaning more on your browser (this is going to be indicated with the [browser] tag), or leaning more on your command line.

4. [browser] You should be able to test whether eXist runs by pointing your browser to http://localhost:8889/ -- though be warned that, for example under Linux, you should rather use Chrome than Chromium (in the latter, you will see the splash screen but then the dashboard is blank, although the database runs fine). Under Chrome, you should see something like the following:

5. [browser] If you then choose to log in as the user "admin" (with the password you set during the installation process), you are going to see something like:

   From here, you may want to check for potential updates to the installed parts of eXist, but we leave that at your discretion. From this spot, you will either use the eXide app from the Dashboard, or abandon the browser-based way and use the Java client.

6. [GitHub] From now on, we will assume that you have either cloned the SIS repository (git clone https://github.com/clarin-eric/standards.git) or downloaded the zipped archive from https://github.com/clarin-eric/standards and unpacked it. Please note that you only need the part under the directory called SIS.

   You will notice that we work with several branches. We only occasionally push to the default branch, "master", so you might want to have a look at the most recent commits to branches "dev" and "formats" and then decide which of them to use. (The "master" branch is practically only used at the time we upload the code to the production instance running at the clarin.eu alias.)

7. [browser] Start the eXide app from the Dashboard, and from its File menu, choose "Manage":

   We will now target the "apps" section, as that is where, by default, eXist expects to see new document collections. In theory, we are now going to create a new collection under "apps" and call it "clarin", and then populate it with the content of the SIS/clarin/ directory from the cloned (or unzipped) repository. In practice, this can be done in a single action, by adding the clarin/ directory directly:

The last thing to be handled is permissions of the file controller.xql. Let's double-click on clarin to open the newly added collection, and then, at the bottom of the list, select controller.xql and press the "i" icon to modify its properties. We need to make it executable for the group "Other" (note the highlighted box below). Remember to click the "apply" button.

At this point, we are all set to use the SIS. Note that, at the very bottom of the collection, the file index.xq resides. You can "Open" it, and then hit "Run". You will be taken to a new tab in the browser and asked for the "admin" user credentials. Afterwards, the SIS is going to load.

7. [alternative] Instead of using eXide in the browser, you can activate the admin client by running the following in your terminal:

   ./{eXist-db-installation-folder}/bin/client.sh

   Note that you need to modify the port in the initial client window. The screenshot below also shows that this setting may be saved in the "Favourites" section, to make the future logins faster:

The initial window of the client, after you've logged in, should be as shown below. Recall that our target is the "apps" section, as that is where, by default, eXist expects to see new document collections.

Let us then double-click on "apps" and proceed to add files (either by Ctrl+S or by clicking the icon with a little '+' in the bottom right). At this point, you need to navigate, inside the client, to where you have cloned or unzipped the SIS package from GitHub, and make sure to select the clarin directory, and click on the button saying "select files or directories to store". You will actually need to click there twice. The first click, on "clarin", will get you to the state presented below:

You may see some scary messages as the files are being added -- be brave and wait until the process completes (these messages are hidden if you're adding the collection via eXide). After the process completes, you should see the newly added directory called clarin. Click on it to enter the SIS source. One further step that you need to perform is adjusting the permissions of the controller.xql -- make sure that the file is executable for 'Other' (note the tick in the 'Execute' column, in the row for "Other"). Remember to "save" the modification!

The installation is done. You can now point your browser at http://localhost:8889/exist/apps/clarin/ and have a go at it. (When asked to, log in with "admin" and the password that you set when installing eXist).

8. oXygen. In order to synchronize eXist-db and the oXygen XML Editor, refer to the documentation at the oXygen Website and/or the documentation provided by eXist. For the automatic setup of the eXist-oXygen connection, you are going to need the port number (8889), the user name ('admin') and your password.

9. What's next? You can either take part in the development either by submitting fixes to, or extensions of, the existing format/standard information, by working in a separate branch or a fork, or you may submit issue reports at https://github.com/clarin-eric/standards/issues . Thanks in advance!

   If you need to see how your updates work in the system, the easiest way is to open eXide and the "manage" dialog (or to use the Java client), delete the "clarin" collection from the database and then import it again (as described above) with your modifications. In cases where your modification is restricted to a single data file (standard or format), you can [delete and] add just that single file, in one of the clients, and you should see the effects after refreshing the view in your browser. You can also drag the changed file(s) from the "Project" view of oXygen into the corresponding folder opened via the database, if you have enabled it in Step 8 above.