Skip to content

Commit 5cc3dd9

Browse files
author
Marcel Neumann
committed
synchronise english and german version
1 parent 80f81af commit 5cc3dd9

File tree

1 file changed

+109
-42
lines changed

1 file changed

+109
-42
lines changed

‎docs/en/setup.md

+109-42
Original file line numberDiff line numberDiff line change
@@ -7,42 +7,120 @@ This documentation describes the process of bootstrapping the vocabulary server.
77
- Adapt configuration file properly and remove unmodified lines.
88
- Database credentials and database name.
99
- Base URL and port.
10-
- **TODO** *Install the `vocabulary-server.jar` and the `application.properties` configuration file both directly into a new folder (e. g. `/opt/digiverso/vocabulary/`)*
10+
- Security token (this must also be configured identically in Goobi).
11+
- Create a Systemd service to start the service automatically.
1112

12-
## Start as systemd service
13-
- **TODO** *Create a systemd service unit for the vocabulary server (The application should be able to correctly shutdown on SIGTERM)*
14-
- **TODO** *Admin documentation here*
15-
- Run `java -jar vocabulary-server-VERSION.jar`.
16-
- If startup succeeds, you will see a line like this after a few seconds:
17-
```bash
18-
Started VocabularyServerApplication in 4.244 seconds (process running for 4.581)
19-
```
13+
## Setting up Goobi Workflow to communicate with the vocabulary server
2014

21-
## Goobi Workflow Setup Communication
22-
- Goobi Workflow uses the new vocabulary server since version `24.07`.
23-
- Configure the `vocabularyServerHost` and `vocabularyServerPort` variables in `goobi_config.properties` according to your vocabulary server configuration.
15+
- Goobi Workflow has been using the new vocabulary server since version `24.07`.
16+
- Configure the variables `vocabularyServerHost`, `vocabularyServerPort` and `vocabularyServerToken` in the `goobi_config.properties` file according to the configuration of your vocabulary server.
2417
- Restart Goobi Workflow for the changes to take effect.
25-
- Navigate to `Administration` > `Vocabularies` to check if everything works. You should see a list of vocabularies if everything is okay (not right now, but after you have created some vocabularies or migrated the existing ones). You will see a red error message if something doesn't work.
26-
27-
## Initial Setup
28-
- For proper operation, the vocabulary server needs some initial data.
29-
- This data contains language specifications (if multi-language vocabularies are used) and field type definitions.
30-
- You can use the following script that installs some sample languages and field types.
31-
- Download the [Initial Data Script](https://jenkins.intranda.com/job/intranda/job/vocabulary-server/job/develop/lastSuccessfulBuild/artifact/install/default_setup.sh).
32-
- Change the `HOST` variable at the top according to the vocabulary server configuration, leave the `/api/v1` suffix unchanged.
33-
- Run the script.
34-
35-
## Security
36-
- You can setup Apache url restrictions in order to secure the vocabulary server from unauthorized access.
37-
- **TODO** *Admins, please find out what and how to do it in detail.*
38-
39-
## Installation Test
40-
- For all commands, change host and port accordingly.
41-
- After the initial setup, check that types were created successfully:
18+
- Navigate to `Administration` > `Vocabularies` to check that everything is working. You should see a list of vocabularies if everything is OK (not now, but after you have created some vocabularies or migrated the existing ones). If something is not working, you will see a red error message.
19+
20+
21+
## Initial setup
22+
23+
- For proper operation, the vocabulary server requires some initial data.
24+
- This data contains language information (if multilingual vocabularies are used) and field type definitions.
25+
- You can use the following script, which installs some sample languages and field types.
26+
- Download the [Initial Data Script](https://github.com/intranda/goobi-vocabulary-server/raw/develop/install/default_setup.sh).
27+
- Change the variables `HOST` and `TOKEN` at the beginning according to the configuration of the vocabulary server, leave the suffix `/api/v1` unchanged.
28+
- Execute the script.
29+
30+
## Installation script
31+
The vocabulary server requires Java 17, the systemd service assumes that Java 17 is the system default.
32+
33+
For the above three points, under Ubuntu:
34+
``bash
35+
export VOC_PORT=8081
36+
export VOC_TOKEN=$(</dev/urandom tr -dc '[:alnum:]' | head -c17)
37+
export VOC_PATH=/opt/digiverso/vocabulary
38+
export VOC_USER=vocabulary
39+
export VOC_SQL_USER=${VOC_USER}
40+
export VOC_SQL_DB=${VOC_USER}
41+
export PW_SQL_VOC=$(</dev/urandom tr -dc '[:alnum:]' | head -c17)
42+
43+
# create install folder
44+
sudo mkdir ${VOC_PATH}
45+
# download and link vocabulary server application file
46+
wget https://github.com/intranda/goobi-vocabulary-server/releases/latest/download/vocabulary-server-core.jar -O - | sudo tee ${VOC_PATH}/vocabulary-server-core.jar >/dev/null
47+
48+
# create system user which will run the service
49+
sudo adduser --system --home ${VOC_PATH}/home --shell /usr/sbin/nologin --no-create-home --disabled-login ${VOC_USER}
50+
51+
# download the vocabulary migration tools
52+
wget https://github.com/intranda/goobi-vocabulary-server/releases/latest/download/migration-tool.zip -O /tmp/migration-tool.zip
53+
sudo unzip /tmp/migration-tool.zip -d "${VOC_PATH}"
54+
55+
# download and set up the config file
56+
wget https://github.com/intranda/goobi-vocabulary-server/releases/latest/download/application.properties -O - | sudo tee ${VOC_PATH}/application.properties >/dev/null
57+
sudo sed -re "s|^(server.port=).*|\1${VOC_PORT}|" \
58+
-e "s|^#?(security.token=).*|\1${VOC_TOKEN}|" \
59+
-e "s|^(spring.datasource.username=).*|\1${VOC_SQL_USER}|" \
60+
-e "s|^(spring.datasource.password=).*|\1${PW_SQL_VOC}|" \
61+
-e "s|^(spring.datasource.url=).*|\1jdbc:mariadb://localhost:3306/${VOC_SQL_DB}|" \
62+
-i ${VOC_PATH}/application.properties
63+
sudo chown ${VOC_USER}: ${VOC_PATH}/application.properties
64+
sudo chmod 600 ${VOC_PATH}/application.properties
65+
66+
# install a systemd service unit file
67+
cat << EOF | sudo tee /etc/systemd/system/vocabulary.service
68+
[Unit]
69+
Description=Goobi Vocabulary Server
70+
After=mysql.service remote-fs.target
71+
Requires=mysql.service remote-fs.target
72+
73+
[Service]
74+
WorkingDirectory=${VOC_PATH}
75+
Restart=always
76+
RestartSec=20s
77+
StartLimitInterval=100s
78+
StartLimitBurst=4
79+
ExecStart=/usr/bin/java -jar vocabulary-server-core.jar
80+
User=${VOC_USER}
81+
NoNewPrivileges=true
82+
ProtectSystem=true
83+
PrivateTmp=yes
84+
85+
[Install]
86+
WantedBy=default.target tomcat9.service
87+
EOF
88+
sudo systemctl daemon-reload
89+
sudo systemctl enable vocabulary.service
90+
91+
# create and configure the database
92+
sudo mysql -e "CREATE DATABASE ${VOC_SQL_DB} CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';
93+
CREATE USER '${VOC_SQL_USER}'@'localhost' IDENTIFIED BY '${PW_SQL_VOC}';
94+
GRANT ALL PRIVILEGES ON ${VOC_SQL_DB}.* TO '${VOC_SQL_USER}'@'localhost' WITH GRANT OPTION;
95+
FLUSH PRIVILEGES;"
96+
97+
# append vocabulary server address to the Goobi workflow config
98+
grep ^vocabularyServerHost= /opt/digiverso/goobi/config/goobi_config.properties || echo "vocabularyServerHost=localhost" | sudo tee -a /opt/digiverso/goobi/config/goobi_config.properties
99+
grep ^vocabularyServerPort= /opt/digiverso/goobi/config/goobi_config.properties || echo "vocabularyServerPort=${VOC_PORT}" | sudo tee -a /opt/digiverso/goobi/config/goobi_config.properties
100+
grep ^vocabularyServerToken= /opt/digiverso/goobi/config/goobi_config.properties || echo "vocabularyServerToken=${VOC_TOKEN}" | sudo tee -a /opt/digiverso/goobi/config/goobi_config.properties
101+
102+
# start the vocabulary server and wait for startup
103+
sudo systemctl restart vocabulary.service & sudo journalctl -u vocabulary.service -f -n 0 | grep -q "Started VocabularyServerApplication in"
104+
105+
# initial set up
106+
wget https://github.com/intranda/goobi-vocabulary-server/raw/develop/install/default_setup.sh -O /tmp/default_setup.sh
107+
bash /tmp/default_setup.sh
108+
109+
## test
110+
curl -s http://localhost:${VOC_PORT}/api/v1/types --header "Authorization: Bearer $VOC_TOKEN" | jq -r '._embedded.fieldTypeList[] .name'
111+
```
112+
113+
## Accessibility
114+
- You can make the vocabulary server accessible from outside by connecting a proxy with access control in front of it.
115+
116+
## Installation test
117+
- Change the host and port accordingly for all commands.
118+
- After the initial setup, check whether the field types have been created successfully:
42119
```bash
43-
curl http://localhost:8081/api/v1/types | jq -r '._embedded.fieldTypeList[] .name'
120+
curl ‘http://localhost:${VOC_PORT:-8081}/api/v1/types’ --header ‘Authorisation: Bearer $VOC_TOKEN’ | jq -r ‘._embedded.fieldTypeList[] .name’
44121
```
45-
- The result should look like:
122+
123+
- The result should look like this:
46124
```bash
47125
Anything
48126
Boolean
@@ -56,14 +134,3 @@ skos:related
56134
skos:closeMatch
57135
skos:exactMatch
58136
```
59-
- If a data migration has been done, check that all vocabularies have been migrated:
60-
```bash
61-
curl http://localhost:8081/api/v1/vocabularies/all | jq -r '._embedded.vocabularyList[] .name'
62-
```
63-
- Check that links resolve correctly (see configuration):
64-
```bash
65-
curl http://localhost:8081/api/v1/records/1 | jq
66-
```
67-
The `_links` JSON element should contain references to other resources.
68-
These URLs should be valid and resolvable.
69-
The host part of these URLs is generated from the request.

0 commit comments

Comments
 (0)