diff --git a/README.md b/README.md index 444a056..b695280 100644 --- a/README.md +++ b/README.md @@ -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** +
+ Table of Contents +
    +
  1. Introduction
    2. +
  2. Run the application
    3. +
  3. Run tests
    4. +
+
-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`.