|
## 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 KIK-Starter allows a very low barrier to entry for experimenting with KIK-Starter without installing anything. This version of KIK-Starter 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 ###
|
|
### Usage ###
|
|
|
|
|
... | @@ -8,7 +8,7 @@ The central installation of VOLT allows a very low barrier to entry for experime |
... | @@ -8,7 +8,7 @@ The central installation of VOLT allows a very low barrier to entry for experime |
|
|
|
|
|
## Decentral use ##
|
|
## Decentral use ##
|
|
|
|
|
|
This is the preferred way to use VOLT in most cases, and is also the only way to use VOLT with your own data.
|
|
This is the preferred way to use KIK-Starter in most cases, and is also the only way to use KIK-Starter with your own data.
|
|
|
|
|
|
### Prerequisites ###
|
|
### Prerequisites ###
|
|
|
|
|
... | @@ -43,11 +43,11 @@ Scenario 0 is the default and requires no configuration. It should only be used |
... | @@ -43,11 +43,11 @@ Scenario 0 is the default and requires no configuration. It should only be used |
|
|
|
|
|
##### Self-signed certificate #####
|
|
##### Self-signed certificate #####
|
|
|
|
|
|
To use the application using a self-signed certificate, you just have to provide a host name using `VOLT_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.
|
|
To use the application using a self-signed certificate, you just have to provide a host name using `KIK-Starter_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 certificate #####
|
|
|
|
|
|
[Let's Encrypt](https://letsencrypt.org) provides free high-quality certificates trusted by most browsers. To use this, your VOLT installation needs to be accessible from the internet on port 80 using the name provided in `VOLT_HOSTNAME`. In addition, you need to provide an email address in `VOLT_EMAIL`, which is used for the issuing.
|
|
[Let's Encrypt](https://letsencrypt.org) provides free high-quality certificates trusted by most browsers. To use this, your KIK-Starter installation needs to be accessible from the internet on port 80 using the name provided in `KIK-Starter_HOSTNAME`. In addition, you need to provide an email address in `KIK-Starter_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.
|
|
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.
|
|
|
|
|
... | @@ -55,18 +55,18 @@ Certificates are renewed twice daily at random times and on restart of the image |
... | @@ -55,18 +55,18 @@ Certificates are renewed twice daily at random times and on restart of the image |
|
|
|
|
|
##### User-supplied certificate #####
|
|
##### 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 `VOLT_KEY` and `VOLT_CERT_CHAIN`.
|
|
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 `KIK-Starter_KEY` and `KIK-Starter_CERT_CHAIN`.
|
|
|
|
|
|
#### Configuration parameter overview ####
|
|
#### Configuration parameter overview ####
|
|
|
|
|
|
| parameter | default | meaning | mandatory in scenarios |
|
|
| parameter | default | meaning | mandatory in scenarios |
|
|
| ---------------- | ------- | ------- | ---------------------- |
|
|
| ---------------- | ------- | ------- | ---------------------- |
|
|
| `VOLT_HOSTNAME` | | The host name users use to access the application | T1, T2 |
|
|
| `KIK-Starter_HOSTNAME` | | The host name users use to access the application | T1, T2 |
|
|
| `VOLT_EMAIL` | | The email used to request cvertificates from Let's Encrypt | T2 |
|
|
| `KIK-Starter_EMAIL` | | The email used to request cvertificates from Let's Encrypt | T2 |
|
|
| `VOLT_KEY` | | Base64 encoded PEM private key | T3 |
|
|
| `KIK-Starter_KEY` | | Base64 encoded PEM private key | T3 |
|
|
| `VOLT_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 |
|
|
| `KIK-Starter_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 VOLT must be base-64 encoded again so that after base64 decoding it will generate a valid certificate/key file.
|
|
Note that while PEM certificates/keys contain base64-encoded data, the values provided to KIK-Starter must be base-64 encoded again so that after base64 decoding it will generate a valid certificate/key file.
|
|
|
|
|
|
#### Application location overview ####
|
|
#### Application location overview ####
|
|
|
|
|
... | @@ -83,11 +83,11 @@ In the default configuartion, you do not *have* to bind any volumes, the applica |
... | @@ -83,11 +83,11 @@ In the default configuartion, you do not *have* to bind any volumes, the applica |
|
#### Examples ####
|
|
#### Examples ####
|
|
|
|
|
|
##### Improved security for a single user #####
|
|
##### Improved security for a single user #####
|
|
To run the VOLT decentral using TLS scenario T1 (self-signed certificate), storing certificates in the current folder on the host system, execute:
|
|
To run the KIK-Starter decentral 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 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
-e VOLT_HOSTNAME='localhost' \
|
|
-e KIK-Starter_HOSTNAME='localhost' \
|
|
-v $( pwd ):/tls \
|
|
-v $( pwd ):/tls \
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
```
|
|
```
|
... | @@ -96,12 +96,12 @@ Note: the `$( pwd )` syntax works on unix-like systems (Linux, Max OS X); on Win |
... | @@ -96,12 +96,12 @@ Note: the `$( pwd )` syntax works on unix-like systems (Linux, Max OS X); on Win |
|
|
|
|
|
##### Imnproved security using Let's Encrypt, faster start-up, and persistence of uploads between restarts #####
|
|
##### Imnproved security using Let's Encrypt, faster start-up, and persistence of uploads between restarts #####
|
|
|
|
|
|
To run the VOLT decentral 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:
|
|
To run the KIK-Starter decentral 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 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
-e VOLT_HOSTNAME='volt.example.com' \
|
|
-e KIK-Starter_HOSTNAME='volt.example.com' \
|
|
-e VOLT_EMAIL='volt@example.com' \
|
|
-e KIK-Starter_EMAIL='volt@example.com' \
|
|
-v $( pwd )/tls:/tls \
|
|
-v $( pwd )/tls:/tls \
|
|
-v $( pwd )/data/uploads:/data/ephemeral \
|
|
-v $( pwd )/data/uploads:/data/ephemeral \
|
|
-v $( pwd )/data/central:/data/persistent \
|
|
-v $( pwd )/data/central:/data/persistent \
|
... | @@ -110,7 +110,7 @@ docker run -tp 8080:80 -p 8443:443 \ |
... | @@ -110,7 +110,7 @@ docker run -tp 8080:80 -p 8443:443 \ |
|
|
|
|
|
Note: the `$( pwd )` syntax works on unix-like systems (Linux, Max OS X); on Windows provide the full path, e.g., `d:\\tls`.
|
|
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 `VOLT_HOSTNAME` and `VOLT_EMAIL` options can be left out:
|
|
After the certificate has been generated, the `KIK-Starter_HOSTNAME` and `KIK-Starter_EMAIL` options can be left out:
|
|
|
|
|
|
```
|
|
```
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
... | @@ -120,4 +120,4 @@ docker run -tp 8080:80 -p 8443:443 \ |
... | @@ -120,4 +120,4 @@ docker run -tp 8080:80 -p 8443:443 \ |
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<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 VOLT installation changes external name, just execute it with the new host name in `VOLT_HOSTNAME` and the appropriate email in `VOLT_EMAIL` to request and use a new certificate instead. |
|
As long as the `/tls` folder is bound to the same host path, KIK-Starter can figure out how to renew the certificate as needed. If the KIK-Starter installation changes external name, just execute it with the new host name in `KIK-Starter_HOSTNAME` and the appropriate email in `KIK-Starter_EMAIL` to request and use a new certificate instead. |
|
|
|
\ No newline at end of file |