README.md 3.68 KB
Newer Older
1
2
3
4
# SADE – Scalable Architecture for Digital Editions

SADE ( Scalable Architecture for Digital Editions) it an application for
[eXist-db](https://exist-db.org) that offers a set of useful features to quickly build a website for digital editions basing on [TEI](http://www.tei-c.org)-encoded texts.
Mathias Goebel's avatar
Mathias Goebel committed
5
6

This is the main application for SADE. It serves as XAR package according to the
7
8
9
10
11
12
13
14
15
[EXPath Packaging System](http://expath.org/spec/pkg) and is created as an application for
[eXist-db](https://exist-db.org).

## Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

### Prerequisites

hynek's avatar
hynek committed
16
* ant >= 1.10.0
17
18
19
20
21

### Local installation

To get a version of SADE running locally on your computer, clone this repository in your preferred git directory:

hynek's avatar
hynek committed
22
```sh
23
24
25
26
27
28
mkdir SADE
cd SADE
git clone git@gitlab.gwdg.de:SADE/SADE.git
```

Once the repository is cloned, run
hynek's avatar
hynek committed
29
30
31

```sh
./build_test
32
33
34
35
36
```

which installs all necessary dependencies and creates a local version of SADE in `/test`.
To start the database, run

hynek's avatar
hynek committed
37
38
```sh
bash test/exist-distribution-*/bin/startup.sh
39
40
41
42
43
```

SADE's backend is now available at `localhost:8080`. To have a look at the website, view `http://localhost:8080/exist/apps/sade/index.html` in your preferred browser.

## The Git repo
hynek's avatar
hynek committed
44

45
This repo contains the sources of the application which contain a brief
Mathias Goebel's avatar
Mathias Goebel committed
46
47
48
49
50
documentation as long as you are not dealing with a fork. Please find the
documentation in the folder `docs` where they are stored in Markdown. Any
default installation of this package serves the documentation as website
integrated in your template and in your instance.

51
### Git hooks
hynek's avatar
hynek committed
52

Mathias Goebel's avatar
Mathias Goebel committed
53
54
55
The folder `.hooks` contains git hook scripts to be executed on certain git
events. The usage of these scripts is recommended, as they ensure a smooth
workflow.
hynek's avatar
hynek committed
56

Mathias Goebel's avatar
Mathias Goebel committed
57
#### pre-commit
hynek's avatar
hynek committed
58

Mathias Goebel's avatar
Mathias Goebel committed
59
60
We test for `DONOTCOMMIT` comments in the code. As long as a comment like this
is in files, no commit is possible.
hynek's avatar
hynek committed
61

Mathias Goebel's avatar
Mathias Goebel committed
62
#### post-commit
hynek's avatar
hynek committed
63

Mathias Goebel's avatar
Mathias Goebel committed
64
65
66
67
On any commit a new artifact is being created, so you can proceed and test it
immediately.

## Build
hynek's avatar
hynek committed
68
69
70
71

```sh
./build_xar
```
Mathias Goebel's avatar
Mathias Goebel committed
72

73
Artifacts will be stored in `.build/`.
Mathias Goebel's avatar
Mathias Goebel committed
74
75
76

The default artifact is the xar package.

Mathias Goebel's avatar
Mathias Goebel committed
77
## Test
hynek's avatar
hynek committed
78
79

`./build_test` will download the specified version of eXist and all dependencies to
Mathias Goebel's avatar
Mathias Goebel committed
80
81
a ready-to-go instance in the `test/` directory. at the first start all tests
will be executed by the `post-install.xq` script. To start the database use
hynek's avatar
hynek committed
82
83
84

```sh
test/exist-distribution-*/bin/startup.sh
Mathias Goebel's avatar
Mathias Goebel committed
85
```
hynek's avatar
hynek committed
86

Mathias Goebel's avatar
Mathias Goebel committed
87
88
89
Guide your favorite browser to the [dashboard](http://localhost:8080/exist/).

### Port settings
hynek's avatar
hynek committed
90

Mathias Goebel's avatar
Mathias Goebel committed
91
92
When the port 8080 is blocked by a different service, simply set different ones
with the following command and restart the database.
hynek's avatar
hynek committed
93
94

```sh
Mathias Goebel's avatar
Mathias Goebel committed
95
96
97
98
99
100
sed -i 's/"8080"/"8090"/g; s/"8443"/"8444"/g' \
  test/eXist-db-4.5.0/tools/jetty/etc/jetty-http.xml \
  test/eXist-db-4.5.0/tools/jetty/etc/jetty.xml \
  test/eXist-db-4.5.0/tools/jetty/etc/jetty-ssl.xml
```

Mathias Goebel's avatar
Mathias Goebel committed
101
## Known Issues
hynek's avatar
hynek committed
102

Mathias Goebel's avatar
Mathias Goebel committed
103
104
105
106
107
108
109
110
111
112
In the unlikely event of cycling to the next digit in TextGrid URIs you may
encounter issues when you going to use an older URI together with a newer that
starts with the same characters. Example: One will publish the text
`textgrid:foo.0` and over time the URI number increases that much, that
another object that should be stored in the database has the URI
`textgrid:foobar.0`, some processes that tests against using `starts-with()`
will fail or may respond with the wrong object. At the end of 2017 we are
dealing with 5 digits of Latin letters and Arabic numbers (a total of 36
different symbols) starting with "3". So it will take another approx. ten
million items to reach the next digit. So we will talk about this later.