-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
73 additions
and
88 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,104 +1,89 @@ | ||
| # OLA-HD Service | ||
| OLA-HD frontend | ||
| =============== | ||
|
|
||
| OLA-HD Service - Ein generischer Dienst für die Langzeitarchivierung historischer Drucke | ||
| The OLA-HD frontend is the frontend for the [OLA-HD Service](https://github.com/subugoe/olahd_backend) build with [Vue.js](https.//vuejs.org). | ||
|
|
||
| **Note** | ||
| <details> | ||
| <summary>Table of Contents</summary> | ||
| <ol> | ||
| <li><a href="#introduction">Introduction</a></li> | ||
| <li><a href="#run-the-application">Run the application</a></li> | ||
| <li><a href="#run-tests">Run tests</a></li> | ||
| </ol> | ||
| </details> | ||
|
|
||
| Das Ziel von OLA-HD Service ist die Entwicklung eines produktiven Dienstes für die Langzeitarchivierung von historischen Drucken im Rahmen von [OCR-D](https://ocr-d.de/). Auf dieser Website kann die prototypische Implementierung des Projekts ausprobiert werden. Über die Suche können in Kürze Archivobjekte gefunden, angesehen und heruntergeladen werden. | ||
|
|
||
| OLA-HD Service wird im Rahmen der DFG-Initiative [OCR-D](https://ocr-d.de/) gefördert. Das Hauptziel von OCR-D ist die konzeptionelle und technische Vorbereitung der Volltexttransformation der im deutschen Sprachraum erschienenen Drucke des 16.-18. Jahrhunderts. Die Aufgabe der automatischen Volltexterkennung wird in ihre einzelnen Prozessschritte zerlegt, die in der Open Source OCR-D-Software nachvollzogen werden können. Dies ermöglicht es, optimale Workflows für die zu prozessierenden Drucke zu erstellen und damit wissenschaftlich verwertbare Volltexte zu generieren. OLA-HD Service bietet einen Dienst für die Langzeitarchivierung dieser Ergebnisse. | ||
| Introduction | ||
| ------------ | ||
| OLA-HD Service is one of the module projects funded within the DFG initiative OCR-D. The main goal | ||
| of OCR-D is the conceptual and technical preparation of the full text transformation of the 16th to | ||
| 18th century prints published in the German language area. The task of automatic full-text | ||
| recognition will be broken down into its individual process steps, which can be reproduced in the | ||
| open source OCR-D software. This makes it possible to create optimal workflows for the prints to be | ||
| processed and thus generate scientifically usable full texts. | ||
|
|
||
| The goal of OLA-HD Service is to develop a productive service for long-term archiving of historical | ||
| prints in the context of OCR-D. This OLA-HD Service builds on the corresponding prototype from | ||
| OCR-D Phase II, extends it according to the requirements of the implementation projects, is | ||
| integrated into the OCR-D framework, and is generically designed and implemented according to the | ||
| tender requirements. | ||
|
|
||
| # Overview | ||
|
|
||
| - [Getting Started (Developers)](#getting-started-developers) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Environment setup](#environment-setup) | ||
| - [Set up `nvm` and the recent stable version of `node.js`](#set-up-nvm-and-the-recent-stable-version-of-nodejs) | ||
| - [Set up `global` project requirements via `npm`](#set-up-global-project-requirements-via-npm) | ||
| - [Clone the repository](#clone-the-repository) | ||
| - [Get the dependencies](#get-the-dependencies) | ||
| - [Usage](#usage) | ||
| - [`development mode` (hot reloading, error reporting, etc.)](#development-mode-hot-reloading-error-reporting-etc) | ||
| - [`Linting`](#linting) | ||
| - [`Testing`](#testing) | ||
| - [`Building` the app for production](#building-the-app-for-production) | ||
|
|
||
|
|
||
| ## Getting Started (Developers) | ||
| Run the application: | ||
| -------------------- | ||
|
|
||
| ### Prerequisites | ||
| To run, the OLA-HD Service currently uses the classic [yarn package | ||
| manager](https://classic.yarnpkg.com/lang/en/). This must be installed to run the frontend. | ||
|
|
||
| To get OLA-HD up and running you should have the following software installed: | ||
|
|
||
| - **curl** | ||
| - **yarn** | ||
|
|
||
| **Note**: | ||
|
|
||
| We recommend to make use of `nvm`, since there might be issues with npm regarding permissions. | ||
| The main purpose of `nvm` is to have multiple node versions installed in regards to different projects which might demand some sort of backwards compatibility. | ||
| It enables you to just switch to the appropriate node version. | ||
| Besides it also keeps track of resolving permission issues, since all your global installations go to your home directory (~/.nvm/) instead of being applied systemwide. | ||
|
|
||
| ### Environment setup | ||
|
|
||
| #### Set up `nvm` and the recent stable version of `node.js` | ||
|
|
||
| **For MAC Users** | ||
| ```bash | ||
| curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash | ||
| nvm install stable | ||
| ``` | ||
|
|
||
| **For Linux/Ubuntu Users** | ||
| ```bash | ||
| sudo apt install curl | ||
| curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash | ||
| ``` | ||
|
|
||
| **Note**: | ||
| After the nvm installation is done, please `restart` your shell session once. That's due to changes to your profile environment. | ||
|
|
||
| #### Set up `global` project requirements via `npm` | ||
|
|
||
| ```bash | ||
| npm install -g yarn | ||
| ### Install and run the application | ||
| Clone this repository | ||
| ``` | ||
|
|
||
| #### Clone the repository | ||
|
|
||
| ```bash | ||
| git clone https://github.com/subugoe/olahd_user_frontend.git | ||
| cd olahd_user_frontend | ||
| ``` | ||
|
|
||
| #### Get the dependencies | ||
|
|
||
| Head over to your project directory, where you just cloned the repository to as described above and get all the dependencies needed by typing: | ||
|
|
||
| ```bash | ||
| cd /path/to/projectdir | ||
| yarn install | ||
| ``` | ||
|
|
||
| That's it. You should now be able to run the Viewer. | ||
|
|
||
| ### Usage | ||
|
|
||
| #### `development mode` (hot reloading, error reporting, etc.) | ||
|
|
||
| ```bash | ||
| yarn serve | ||
| ### Install the project dependencies | ||
| `yarn install` | ||
|
|
||
| ### Set OLA-HD Service backend URL | ||
| The frontend needs the backend to query search results and other data. The connection is set in the | ||
| file `src/axios-config.ts`. By default, the application is supposed to run with Docker, so the | ||
| `baseURL` is set to '/api/'. This is because the backend is expected to run on the same host and to | ||
| be available at path `api`. For development purposes, this could be changed to a local running | ||
| OLA-HD backend: `http://localhost:8080` or to the running service: `https://ola-hd.ocr-d.de/api`. | ||
|
|
||
| ### Local startup | ||
| `yarn run dev` starts the frontend on the local machine. | ||
|
|
||
| ### Docker startup | ||
| The frontend is supposed to be run together with the | ||
| [OLA-HD Service backend](https://github.com/subugoe/olahd_backend). Therefore docker-compose.yml is | ||
| provided in this repository. It expects the backend to be running alongside and in the same network | ||
| called `olahd`. If the backend runs according to its documentation the frontend can be started | ||
| simply with `docker-compose -f docker-compose.yml up -d` or with `docker-compose -f | ||
| docker-compose.yml -f docker-compose.https.yaml up -d` if HTTPS is used. In the latter case the | ||
| file `docker-compose.https.yaml` must be created according to `docker-compose.https.example.yaml`. | ||
|
|
||
| ### Keycloak authentication | ||
| By default users are authenticated through the backend. Keycloak can optionally be configured to be | ||
| used to authenticated users. See `docker.env` for more information. | ||
|
|
||
|
|
||
| Run tests: | ||
| ---------- | ||
| OLA-HD Service uses Cypress E2E to test the application. The tests are executed on a running OLA-HD | ||
| Service application. Therefore the service must run locally. It is also possible for example to run | ||
| the tests on a remote-running instance of the service. The URL of the service (where the frontend is | ||
| available) must be set to `baseUrl` in the file `cypress.config.js`. | ||
|
|
||
| The tests can be started with `yarn run cypress open` which starts Cypress in a browser for running | ||
| the tests. | ||
|
|
||
| For some of the tests environment variables are needed. The password is necessary to upload data to | ||
| the OLA-HD Service. The environment variables can be set in the file `cypres.env.json`, for example: | ||
| ``` | ||
|
|
||
| #### `Testing` | ||
|
|
||
| To test, run the application which loads applucation on port 8080, open a new terminal tab and run the below command: | ||
|
|
||
| ```bash | ||
| yarn cypress | ||
| { | ||
| "PASSWORD": "xyz" | ||
| } | ||
| ``` | ||
|
|
||
| The OLAHD Service uses **Cypress E2E**; test suite. | ||
|
|
||
| Tests reside under **cypress/e2e/** and are supposed to have a file ending of either `*.cy.ts`. |