Dear Gitlab users, due to maintenance reasons, Gitlab will not be available on Thursday 30.09.2021 from 5:00 pm to approximately 5:30 pm.

Commit b95ecc17 authored by Andreas Wagner's avatar Andreas Wagner
Browse files

Change wording in README.

parent 3d834431
......@@ -6,9 +6,9 @@
[![Release](https://img.shields.io/gitlab.gwdg.de/rg-mpg-de/tei2zenodo.svg?style=flat-square)](https://gitlab.gwdg.de/rg-mpg-de/tei2zenodo/releases/latest)
-->
This is the "TEI to Zenodo service" developed at the [Max Planck Institute for European Legal History](http://www.rg.mpg.de/). It is meant to provide a means to quickly push [TEI-encoded XML files](https://tei-c.org/guidelines/p5/) to [Zenodo](https://about.zenodo.org/) deposits, thereby assigning them a DOI identifier and committing them to long-term archival. The software's REST API accepts direct file uploads with POST requests, or webhook calls via POST requests to another one of its endpoints. The idea is that you configure a webhook in your git repository that calls the software, which then looks up and retrieves the TEI files from the repository and creates individual zenodo deposits for each of them.
This is the "TEI to Zenodo Webservice" software developed at the [Max Planck Institute for European Legal History](http://www.rg.mpg.de/). It is meant to provide a means to quickly push [TEI-encoded XML files](https://tei-c.org/guidelines/p5/) to [Zenodo](https://about.zenodo.org/) deposits, thereby assigning them a DOI identifier and committing them to long-term archival. The service's REST API accepts direct file uploads with POST requests, or webhook calls via POST requests to another one of its endpoints. The idea is that you configure a webhook in your git repository that calls the service, which then looks up and retrieves the TEI files from the repository and creates individual zenodo deposits for each of them.
This software:
This webservice:
- accepts and processes [github webhooks](https://developer.github.com/webhooks/) (currently of the `push` type only)
- identifies all files that have been modified in the action that triggered the webhook
......@@ -20,7 +20,7 @@ This software:
- is capable of looking up an existing deposit (if the TEI file mentions its own zenodo DOI entry) and creating a new version of it. This new version will have a new DOI, so the software deletes the old DOI and adds the new one before uploading the file to zenodo
<img align="left" style="margin-right:10px;" src="https://upload.wikimedia.org/wikipedia/commons/d/d1/Emblem-notice.svg"/>
Note that, since the XPath library that this software uses only supports basic XPath functions, you cannot really parse or manipulate the values via configuration settings. This means that tei2zenodo presupposes that you use some of zenodo's controlled vocabulary in your TEI markup. For example, the license name or the editor roles in your TEI files are expected to be compatible with zenodo. You could, for example, use the `@n`-attribute of TEI's `<editor>` element to hold the required string like "cc-by" or use zenodo's controlled vocabulary for contributor types to specify the TEI `<editor>`'s `@role`-attribute...
Note that, since the XPath library that this service uses only supports basic XPath functions, you cannot really parse or manipulate the values via configuration settings. This means that tei2zenodo presupposes that you use some of zenodo's controlled vocabulary in your TEI markup. For example, the license name or the editor roles in your TEI files are expected to be compatible with zenodo. You could, for example, use the `@n`-attribute of TEI's `<editor>` element to hold the required string like "cc-by" or use zenodo's controlled vocabulary for contributor types to specify the TEI `<editor>`'s `@role`-attribute...
## Installation \& Setup
......@@ -32,7 +32,7 @@ There are several ways of obtaining the software. It is not necessary to install
3. If you want to compile the source code manually yourself, you need the [Go compiler](https://golang.org/) as well. Then, after retrieving the source code, either by cloning the git repository or by using one of the "download source code" options, you can compile it in its main directory with the command `go build -ldflags "-s -w" -o t2zd cmd/t2zd/main.go`. You can even skip the optimization switches (`-ldflags ...`) or the naming part (`-o t2zd`) and just say `go build cmd/t2zd/main.go` (and use `main` as the command to launch the server), but the longer command is the one I am using most of the time.
Interestingly, it is trivial to cross-compile code with Go, in other words, you can compile the software for many different target systems on your system. For instance, you could compile on your Windows Desktop, copy the executable over to your Linux server and run the software there. There is a good description of the process and of the various possible combinations of platform and architecture over at [Digitalocean](https://www.digitalocean.com/community/tutorials/how-to-build-go-executables-for-multiple-platforms-on-ubuntu-16-04#step-4-%E2%80%94-building-executables-for-different-architectures).
Interestingly, it is trivial to cross-compile code with Go, in other words, you can compile the software for many different target systems on your system. For instance, you could compile on your Windows Desktop, copy the executable over to your Linux server and run the webservice there. There is a good description of the process and of the various possible combinations of platform and architecture over at [Digitalocean](https://www.digitalocean.com/community/tutorials/how-to-build-go-executables-for-multiple-platforms-on-ubuntu-16-04#step-4-%E2%80%94-building-executables-for-different-architectures).
## Configuration
......@@ -87,7 +87,7 @@ Here is a complete zenodo config section:
In the `Git` config section, besides the obvious `host` and `token` keys, there are several keys that allow you to control what is being handled and how:
Since the software can receive hooks from no matter where, and relies on information contained in the hook in order to "follow its nose" and retrieve files that it then uploads to zenodo, you can filter in many ways what is being processed: if you add a [secret](https://developer.github.com/webhooks/securing/) to your github repository, you can add this string to a configuration setting calles `secret`, which is used to check incoming messages against their signatures. You can also specify a repository in the `repo` key, the hooks of which will be processed exclusively. If hooks from other repositories come in, they will be ignored. If you leave the `repo` key empty, on the other hand, they will be processed as well.
Since the webservice can receive hooks from no matter where, and relies on information contained in the hook in order to "follow its nose" and retrieve files that it then uploads to zenodo, you can filter in many ways what is being processed: if you add a [secret](https://developer.github.com/webhooks/securing/) to your github repository, you can add this string to a configuration setting calles `secret`, which is used to check incoming messages against their signatures. You can also specify a repository in the `repo` key, the hooks of which will be processed exclusively. If hooks from other repositories come in, they will be ignored. If you leave the `repo` key empty, on the other hand, they will be processed as well.
The same holds for the `user` key: If you specify a value here, only hooks initiated by this github user will be processed. (In the case of "push" webhooks, the payload's `pusher.name` field is compared to this config value.)
......@@ -171,7 +171,7 @@ To set up a [github webhook](https://developer.github.com/webhooks/) that trigge
## API endpoints
By default, this software listens at the following API endpoints:
By default, this webservice listens at the following API endpoints:
- /api/v1/file (POST, content-type: application/xml - receives a TEI file and a ?doPublish=(False|True) url query parameter)
- /api/v1/hooks/receivers/github/events/ (POST)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment