Skip to content

Changes

Page history
Create Usage authored by Michael Westergaard's avatar Michael Westergaard
Hide whitespace changes
Inline Side-by-side
Usage.md 0 → 100644
View page @ ace333bd
## Central use ##
The central installation of VKV allows a very low barrier to entry for experimenting with VKV without installing anything. This version of VKV 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.
### Usage ###
- In a browser, navigate to [frontend.production.vkv.kik-v.ocs.nu](https://frontend.production.vkv.kik-v.ocs.nu) (or click the link)
## Decentral use ##
This is the preferred way to use VKV in most cases, and is also the only way to use VKV with your own data.
### Prerequisites ###
- [Install Docker](https://docs.docker.com/get-docker/)
### Start up Frontend ###
- Execute
```
docker run -tp 8080:80 -p 8443:443 registry.istandaarden.nl/kik-v/vkv/vkv/frontend:<version>
```
where ``<version>`` is the desired version or ``latest`` to automatically start the latest version.
### Connect ###
- In a browser, navigate to [localhost:8080](http://localhost:8080) (or click the link)
### Frontend configuration ###
The frontend is designed to be usable without any configuration when using the application the simplest scenario of a sinhle user running the application on their own computer. For other scenarios, like running the application shared among multiple users, some configuration is needed.
#### TLS Configuration ####
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:
T0) no tls encryption
T1) using a self-signed certificate,
T2) using a Let's Encrypt automatically provisioned certificate, and
T3) using a user-supplied certificate.
Scenario 0 is the default and requires no configuration. It should only be used in a single-user scenario.
##### Self-signed certificate #####
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.
##### Let's Encrypt certificate #####
[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.
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.
Certificates are renewed twice daily at random times and on restart of the image.
##### User-supplied certificate #####
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`.
#### Configuration parameter overview ####
| parameter | default | meaning | mandatory in scenarios |
| ---------------- | ------- | ------- | ---------------------- |
| `VKV_HOSTNAME` | | The host name users use to access the application | T1, T2 |
| `VKV_EMAIL` | | The email used to request cvertificates from Let's Encrypt | T2 |
| `VKV_KEY` | | Base64 encoded PEM private key | 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 |
Note that while PEM certificates/keys contain base64-encoded data, the values provided to VKV must be base-64 encoded again so that after base64 decoding it will generate a valid certificate/key file.
#### Application location overview ####
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).
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.
| location | name | purpose | mount when |
| ------------------ | ------------------- | ----------------------------------- | ---------- |
| `/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 VKV 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/vkv/vkv/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 VKV 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='vkv.example.com' \
-e VKV_EMAIL='vkv@example.com' \
-v $( pwd )/tls:/tls \
-v $( pwd )/data/uploads:/data/ephemeral \
-v $( pwd )/data/central:/data/persistent \
registry.istandaarden.nl/kik-v/vkv/vkv/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/vkv/vkv/frontend:<version>
```
As long as the `/tls` folder is bound to the same host path, VKV 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.