From 7ffabd12314ab10fe82276d707b27e28fd027dad Mon Sep 17 00:00:00 2001
From: Thomas Bock <thomas.bock@ptb.de>
Date: Tue, 6 Dec 2022 12:44:35 +0100
Subject: [PATCH] readme update
---
README.md | 132 +++++++++++++++++++++++++++---------------------------
1 file changed, 66 insertions(+), 66 deletions(-)
diff --git a/README.md b/README.md
index e4714b9..5a3b939 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,61 @@
# vl-dcc
-DCC generation for the vacumm laboratory.
-## install & activate
+The DCC generation of the vacuum laboratory.
-Create a file `.git/hooks/pre-push` in the GIT repository with the following
+## API
+
+### `vl-dcc/<cer_doc_id>` (GET)
+
+Returns a `xml` version (the DCC) of a pre-generated `json` document:
+
+```shell
+curl -s http://localhost:5006/vl-dcc/2019-75046 > dcc-2019-75046.xml
+```
+
+Returns the DCC and validation at once:
+
+```shell
+curl -s http://a73434:5006/vl-dcc/2019-75046 | \
+ curl -s -X POST -H "Content-Type: text/xml" -d @- http://a73434:5005/validate
+```
+
+### `update` (POST)
+
+The update endpoint pulls the latest program version from origin master
+
+```
+http://server:port/update
+```
+
+This URL has to be specified in the GitLab server under "Settings /
+Webhooks" (no secret token). "Tag Push Events" need to be activated. The
+following information sent by GitLab is evaluated in order to obtain
+all files of the repository:
+
+```json
+{
+ "repository": {
+ "homepage": "https://a75436.berlin.ptb.de/vaclab/vl-dcc",
+ "name": "vl-dcc"
+ }
+}
+```
+
+### `version` (GET)
+
+```shell
+curl -s http://localhost:5006/version
+```
+
+## Installation and activation
+
+Create a file `.git/hooks/pre-push` in the GIT repository with the following
content:
```shell
#!/bin/bash
-# In the case of "git push --tags", writes the short tag value to the
+# In the case of "git push --tags", writes the short tag value to the
# VERSION file in the top level directory of the Git repository
toplevel=$(git rev-parse --show-toplevel)
@@ -38,7 +84,7 @@ Then make this file executable:
chmod 755 .git/hooks/pre-push
```
-Do the following steps with root permission on the server installation:
+Do the following steps with root permission or sudo on the server installation:
```shell
mkdir -p /usr/local/share/vl-dcc
@@ -46,7 +92,7 @@ cd /usr/local/share/vl-dcc
curl --silent --insecure --output - \
https://a75436.berlin.ptb.de/vaclab/vl-dcc/-/archive/master/vl-dcc-master.tar \
| tar xf - --strip-components=1 # only once
-sudo apt install python3-pip # openSUSE: sudo zypper in python3-pip
+sudo apt install python3-pip # openSUSE: sudo zypper in python3-pip
python3 -m venv .
source bin/activate
pip3 install pip-tools
@@ -56,83 +102,37 @@ chown -R nobody.nogroup $PWD # openSUSE: chown -R nobody.nobody $PWD
systemctl daemon-reload # if already exist
systemctl link $PWD/vl-dcc.service
systemctl enable vl-dcc.service # make permanent
-systemctl start vl-dcc.service
+systemctl start vl-dcc.service
systemctl status vl-dcc.service # running?
journalctl -f --unit vl-dcc.service # run-time check
```
-## api
-
-### vl-dcc/<cer_doc_id> (GET)
-
-Returns a xml version of a certificate-document:
-
-```
-curl -s http://localhost:5006/vl-dcc/2019-75046 > dcc-2019-75046.xml
-```
-
-Returns a xml version of a certificate-document with validation at once:
-
-```
-curl -s http://a73434:5006/vl-dcc/2019-75046 | \
- curl -s -X POST -H "Content-Type: text/xml" -d @- http://a73434:5005/validate
-```
-
-### zz (GET)
-
-returns a xml version based on the dummy certificate-document (`zz.json`)
-for test purpose.
-
-```
-curl -s http://localhost:5006/zz > zz.xml
-```
-
-### update (POST)
-
-pulls the latest program version from origin master
-
-```
-http://server:port/update
-```
-
-This URL must be specified in the GitLab server under "Settings / Webhooks" (no
-secret token). "Tag Push Events" must be activated. The following information
-sent by GitLab is evaluated in order to obtain all files of the Ropositorium
-via the requested tar stream:
-
-```json
-{
- ...
- "repository": {
- "homepage": "https://a75436.berlin.ptb.de/vaclab/vl-dcc",
- "name": "vl-dcc"
- }
- ...
-}
-```
-
-### version (GET)
-
-```
-curl -s http://localhost:5006/version
-```
-
-## More hints
+## Hints
Canonicalization and prettifying:
-```bash
+```shell
./pretty_c14n.py before.xml after.xml
```
Pretty printing the xml code:
-```bash
+```shell
cat foo.xml | tidy -xml --indent auto --indent-cdata yes --quiet yes \
--wrap 0 --tab-size 2 - > bar.xml
```
+The /zz (GET) endpoint
+
+```shell
+curl -s http://localhost:5006/zz > zz.xml
+```
+returns a xml version based on the dummy certificate-document (`zz.json`)
+for test purpose.
+## TODO
+* update `zz.json`
+* allow json POST
--
GitLab