Skip to content

Changes

Page history
Update Usage authored by Desy Kakiay's avatar Desy Kakiay
Hide whitespace changes
Inline Side-by-side
Usage.md
View page @ 2a93fb07
# Nederlandstalig # # _Nederlandstalig _#
## Central use ## ## Centraal gebruik ##
The central installation of VOLT allows a very low barrier to entry for experimenting with VOLT without installing anything. This version of VOLT does not allow uploading your own data, so it is only possible to experiment with the provided test data. To use your own data, check the decentral use section below. De centrale installatie van VOLT zorgt voor een zeer lage instapdrempel om te experimenteren met VOLT zonder iets te installeren. Deze versie van VOLT staat het uploaden van je eigen data niet toe, dus het is alleen mogelijk om te experimenteren met de aangeleverde testdata. Om uw eigen gegevens te gebruiken, kijkt u in het gedeelte over decentraal gebruik hieronder.
### Usage ### ### Gebruik ###
- In a browser, navigate to [frontend.acceptance.volt.kik-v.ocs.nu](https://frontend.acceptance.volt.kik-v.ocs.nu) (or click the link) - Navigeer in een browser naar [frontend.acceptance.volt.kik-v.ocs.nu] (https://frontend.acceptance.volt.kik-v.ocs.nu) (of klik op de link)
## Decentral use ## ## Decentraal gebruik ##
This is the preferred way to use VOLT in most cases, and is also the only way to use VOLT with your own data. Dit is in de meeste gevallen de beste manier om VOLT te gebruiken, en het is ook de enige manier om VOLT te gebruiken met uw eigen gegevens.
### Prerequisites ### ### Vereisten ###
- [Install Docker](https://docs.docker.com/get-docker/) - [Installeer Docker] (https://docs.docker.com/get-docker/)
### Start up Frontend ### ### Start Frontend ###
- Execute - Uitvoeren
``` ``
docker run -tp 8080:80 -p 8443:443 registry.istandaarden.nl/kik-v/volt/frontend:<version> docker run -tp 8080: 80 -p 8443: 443 registry.istandaarden.nl/kik-v/volt/frontend: <versie>
``` ``
where ``<version>`` is the desired version or ``latest`` to automatically start the latest version. waarbij `` <versie> '' de gewenste versie is of `` nieuwste '' om automatisch de nieuwste versie te starten.
### Connect ### ### Aansluiten ###
- In a browser, navigate to [localhost:8080](http://localhost:8080) (or click the link) - Navigeer in een browser naar [localhost: 8080] (http: // localhost: 8080) (of klik op de link)
### Frontend configuration ### ### Frontend-configuratie ###
The frontend is designed to be usable without any configuration when using the application the simplest scenario of a single user running the application on their own computer. For other scenarios, like running the application shared among multiple users, some configuration is needed. De frontend is ontworpen om zonder enige configuratie te kunnen worden gebruikt bij gebruik van de applicatie, het eenvoudigste scenario van een enkele gebruiker die de applicatie op zijn eigen computer draait. Voor andere scenario's, zoals het uitvoeren van de applicatie die door meerdere gebruikers wordt gedeeld, is enige configuratie nodig.
#### TLS Configuration #### #### TLS-configuratie ####
TLS should always be used when the application is run on a computer different from the one of the sole user. These scenarios are supported, in rough order of complexity: TLS moet altijd worden gebruikt als de toepassing op een andere computer wordt uitgevoerd dan die van de enige gebruiker. Deze scenario's worden ondersteund, in grove volgorde van complexiteit:
T0) no tls encryption T0) geen tls-codering
T1) using a self-signed certificate, T1) met behulp van een zelfondertekend certificaat,
T2) using a Let's Encrypt automatically provisioned certificate, and T2) met behulp van een automatisch ingericht Let's Encrypt-certificaat, en
T3) using a user-supplied certificate. T3) met behulp van een door de gebruiker geleverd certificaat.
Scenario 0 is the default and requires no configuration. It should only be used in a single-user scenario. Scenario 0 is de standaardinstelling en vereist geen configuratie. Het mag alleen worden gebruikt in een scenario voor één gebruiker.
##### Self-signed certificate ##### ##### Zelfondertekend certificaat #####
To use the application using a self-signed certificate, you just have to provide a host name using `VKV_HOSTNAME`. The application automatically provisions a self-signed certificate. This means users will get a warning and have to manually trust the certificate. Make sure you mount the certificate storage to persistent storage (see below) or the application will provision a new certificate each time, leading users having to accept it every time. Om de applicatie te gebruiken met een zelfondertekend certificaat, hoeft u alleen maar een hostnaam op te geven met `VKV_HOSTNAME`. De applicatie levert automatisch een zelfondertekend certificaat. Dit betekent dat gebruikers een waarschuwing krijgen en het certificaat handmatig moeten vertrouwen. Zorg ervoor dat u de certificaatopslag koppelt aan permanente opslag (zie hieronder), anders levert de toepassing elke keer een nieuw certificaat, waardoor gebruikers het elke keer moeten accepteren.
##### Let's Encrypt certificate ##### ##### Let's Encrypt certificaat #####
[Let's Encrypt](https://letsencrypt.org) provides free high-quality certificates trusted by most browsers. To use this, your VKV installation needs to be accessible from the internet on port 80 using the name provided in `VKV_HOSTNAME`. In addition, you need to provide an email address in `VKV_EMAIL`, which is used for the issuing. [Let's Encrypt] (https://letsencrypt.org) biedt gratis certificaten van hoge kwaliteit die door de meeste browsers worden vertrouwd. Om dit te gebruiken, moet je VKV-installatie toegankelijk zijn vanaf internet op poort 80 met de naam die is opgegeven in `VKV_HOSTNAME`. Bovendien moet u een e-mailadres opgeven in `VKV_EMAIL`, dat wordt gebruikt voor de uitgifte.
Make sure you mount the certificate storage to persistent storage (see below); Let's Encrypt allows re-issuing a certificate a couple of times, but will refuse after that, so if the certificates are not stored persistently, TLS will break after a few restarts. Zorg ervoor dat u de certificaatopslag koppelt aan permanente opslag (zie hieronder); Let's Encrypt maakt het mogelijk een certificaat een paar keer opnieuw uit te geven, maar zal daarna weigeren, dus als de certificaten niet permanent worden opgeslagen, zal TLS na een paar herstarts breken.
Certificates are renewed twice daily at random times and on restart of the image. Certificaten worden tweemaal daags vernieuwd op willekeurige tijdstippen en bij herstart van de image.
##### User-supplied certificate ##### ##### Door gebruiker geleverd certificaat #####
This option is for more advanced users with more specific needs (e.g., if you must use Staat der Nederlanden PKIoverheid certificates) or where the application is not reachable from the internet (so the standard Let's Encrypt certification procedure is not operational). To make this work, provide `VKV_KEY` and `VKV_CERT_CHAIN`. Deze optie is voor meer gevorderde gebruikers met meer specifieke behoeften (bijvoorbeeld als u Staat der Nederlanden PKIoverheid certificaten moet gebruiken) of waar de applicatie niet bereikbaar is vanaf internet (dus de standaard Let's Encrypt certificeringsprocedure is niet operationeel). Om dit te laten werken, geeft u `VKV_KEY` en` VKV_CERT_CHAIN` op.
#### Configuration parameter overview #### #### Overzicht configuratieparameters ####
| parameter | default | meaning | mandatory in scenarios | | parameter | standaard | betekenis | verplicht in scenario's |
| ---------------- | ------- | ------- | ---------------------- | | ---------------- | ------- | ------- | ---------------------- |
| `VKV_HOSTNAME` | | The host name users use to access the application | T1, T2 | | `VKV_HOSTNAME` | | De hostnaam die gebruikers gebruiken om toegang te krijgen tot de applicatie | T1, T2 |
| `VKV_EMAIL` | | The email used to request cvertificates from Let's Encrypt | T2 | | `VKV_EMAIL` | | De e-mail die wordt gebruikt om cvertificaten aan te vragen bij Let's Encrypt | T2 |
| `VKV_KEY` | | Base64 encoded PEM private key | T3 | | `VKV_KEY` | | Base64-gecodeerde PEM-privésleutel | T3 |
| `VKV_CERT_CHAIN` | | Base64 encoded PEM certificate corresponding to the above key and host name. Should also preferably contain intermediate certificates until a trusted root. | T3 | | `VKV_CERT_CHAIN` | | Base64-gecodeerd PEM-certificaat dat overeenkomt met de bovenstaande sleutel en hostnaam. Bevat bij voorkeur ook tussenliggende certificaten tot een vertrouwde root. | T3 |
Note that while PEM certificates/keys contain base64-encoded data, the values provided to VOLT must be base-64 encoded again so that after base64 decoding it will generate a valid certificate/key file. Merk op dat hoewel PEM-certificaten / -sleutels base64-gecodeerde gegevens bevatten, de waarden die aan VOLT worden verstrekt opnieuw base-64-gecodeerd moeten zijn, zodat het na base64-decodering een geldig certificaat / sleutelbestand genereert.
#### Application location overview #### #### Overzicht toepassingslocatie ####
Some application locations have special meaning and can/should be mapped to persistent locations using [bind mounts](https://docs.docker.com/storage/bind-mounts/) or [volumes](https://docs.docker.com/storage/volumes/) (Docker), or using [persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (Kubernetes). Sommige toepassingslocaties hebben een speciale betekenis en kunnen / zouden moeten worden toegewezen aan permanente locaties met behulp van [bind mounts] (https://docs.docker.com/storage/bind-mounts/) of [volumes] (https: //docs.docker .com / storage / volumes /) (Docker), of met behulp van [persistente volumes] (https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (Kubernetes).
In the default configuartion, you do not *have* to bind any volumes, the application will work just fine, but mounting certain volumes can have positive impact on start-up speed or preserving data between restarts. If using either of TLS scenarios T1 and T2, you will run into problems if you do not mount at least the certificate store persistently. In de standaardconfiguratie hoef je * geen * volumes te binden, de applicatie zal prima werken, maar het aankoppelen van bepaalde volumes kan een positieve invloed hebben op de opstartsnelheid of het bewaren van gegevens tussen herstarts. Als u een van de TLS-scenario's T1 en T2 gebruikt, zult u problemen tegenkomen als u het certificaatarchief niet permanent koppelt.
| location | name | purpose | mount when | | plaats
| ------------------ | ------------------- | ----------------------------------- | ---------- |
| `/data/persistent` | Persistent storage | Data retrieved from central service | Improve start-up time by preserving downloaded ontology updates between application restarts. Data here is not sensitive. |
| `/data/ephemeral` | Ephememeral storage | Data uploaded by user | Retain uploaded data between application restarts. Can be useful if the application is restarted often but be aware that this data may be sensitive. |
| `/tls` | Certificate storage | TLS certificates | When using TLS scenarios T1 and T2 above. |
#### Examples ####
##### Improved security for a single user #####
To run the VOLT frontend using TLS scenario T1 (self-signed certificate), storing certificates in the current folder on the host system, execute:
```
docker run -tp 8080:80 -p 8443:443 \
-e VKV_HOSTNAME='localhost' \
-v $( pwd ):/tls \
registry.istandaarden.nl/kik-v/volt/frontend:<version>
```
Note: the `$( pwd )` syntax works on unix-like systems (Linux, Max OS X); on Windows provide the full path, e.g., `d:\\tls`.
##### Imnproved security using Let's Encrypt, faster start-up, and persistence of uploads between restarts #####
To run the VOLT frontend using TLS scenario T2 (Let's Encrypt certificate), storing certificates in a `tls` folder under the current folder, storing uploaded data in `data/uploads`, and storing updates from the central service in `data/central`, execute:
```
docker run -tp 8080:80 -p 8443:443 \
-e VKV_HOSTNAME='volt.example.com' \
-e VKV_EMAIL='volt@example.com' \
-v $( pwd )/tls:/tls \
-v $( pwd )/data/uploads:/data/ephemeral \
-v $( pwd )/data/central:/data/persistent \
registry.istandaarden.nl/kik-v/volt/frontend:<version>
```
Note: the `$( pwd )` syntax works on unix-like systems (Linux, Max OS X); on Windows provide the full path, e.g., `d:\\tls`.
After the certificate has been generated, the `VKV_HOSTNAME` and `VKV_EMAIL` options can be left out:
```
docker run -tp 8080:80 -p 8443:443 \
-v $( pwd )/tls:/tls \
-v $( pwd )/data/uploads:/data/ephemeral \
-v $( pwd )/data/central:/data/persistent \
registry.istandaarden.nl/kik-v/volt/frontend:<version>
```
As long as the `/tls` folder is bound to the same host path, VOLT can figure out how to renew the certificate as needed. If the VKV installation changes external name, just execute it with the new host name in `VKV_HOSTNAME` and the appropriate email in `VKV_EMAIL` to request and use a new certificate instead.
# English # # _English_ #
## Central use ## ## Central use ##
The central installation of VOLT allows a very low barrier to entry for experimenting with VOLT without installing anything. This version of VOLT does not allow uploading your own data, so it is only possible to experiment with the provided test data. To use your own data, check the decentral use section below. The central installation of VOLT allows a very low barrier to entry for experimenting with VOLT without installing anything. This version of VOLT does not allow uploading your own data, so it is only possible to experiment with the provided test data. To use your own data, check the decentral use section below.
......