... | @@ -4,7 +4,7 @@ The central installation of KIK-Starter allows a very low barrier to entry for e |
... | @@ -4,7 +4,7 @@ The central installation of KIK-Starter allows a very low barrier to entry for e |
|
|
|
|
|
### Usage ###
|
|
### Usage ###
|
|
|
|
|
|
- In a browser, navigate to [decentral.acceptance.volt.kik-v.ocs.nu](https://decentral.acceptance.volt.kik-v.ocs.nu) (or click the link)
|
|
- In a browser, navigate to [decentral.acceptance.starter.kik-v.ocs.nu](https://decentral.acceptance.starter.kik-v.ocs.nu) (or click the link)
|
|
|
|
|
|
## Decentral use ##
|
|
## Decentral use ##
|
|
|
|
|
... | @@ -18,7 +18,7 @@ This is the preferred way to use KIK-Starter in most cases, and is also the only |
... | @@ -18,7 +18,7 @@ This is the preferred way to use KIK-Starter in most cases, and is also the only |
|
|
|
|
|
- Execute
|
|
- Execute
|
|
```
|
|
```
|
|
docker run -tp 8080:80 -p 8443:443 registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
docker run -tp 8080:80 -p 8443:443 registry.istandaarden.nl/kik-v/starter/decentral:<version>
|
|
```
|
|
```
|
|
where ``<version>`` is the desired version or ``latest`` to automatically start the latest version.
|
|
where ``<version>`` is the desired version or ``latest`` to automatically start the latest version.
|
|
|
|
|
... | @@ -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_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 KIK-Starter 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_HOSTNAME`. In addition, you need to provide an email address in `KIK_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,16 +55,16 @@ Certificates are renewed twice daily at random times and on restart of the image |
... | @@ -55,16 +55,16 @@ 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_KEY` and `KIK_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_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_EMAIL` | | The email used to request cvertificates from Let's Encrypt | T2 |
|
|
| `VOLT_KEY` | | Base64 encoded PEM private key | T3 |
|
|
| `KIK_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_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 KIK-Starter 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.
|
|
|
|
|
... | @@ -87,9 +87,9 @@ To run the KIK-Starter decentral using TLS scenario T1 (self-signed certificate) |
... | @@ -87,9 +87,9 @@ To run the KIK-Starter decentral using TLS scenario T1 (self-signed certificate) |
|
|
|
|
|
```
|
|
```
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
-e VOLT_HOSTNAME='localhost' \
|
|
-e KIK_HOSTNAME='localhost' \
|
|
-v $( pwd ):/tls \
|
|
-v $( pwd ):/tls \
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
registry.istandaarden.nl/kik-v/starter/decentral:<version>
|
|
```
|
|
```
|
|
|
|
|
|
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`.
|
... | @@ -100,24 +100,24 @@ To run the VOLT decentral using TLS scenario T2 (Let's Encrypt certificate), sto |
... | @@ -100,24 +100,24 @@ To run the VOLT decentral using TLS scenario T2 (Let's Encrypt certificate), sto |
|
|
|
|
|
```
|
|
```
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
-e VOLT_HOSTNAME='volt.example.com' \
|
|
-e KIK_HOSTNAME='starter.example.com' \
|
|
-e VOLT_EMAIL='volt@example.com' \
|
|
-e KIK_EMAIL='starter@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 \
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
registry.istandaarden.nl/kik-v/starter/decentral:<version>
|
|
```
|
|
```
|
|
|
|
|
|
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_HOSTNAME` and `KIK_EMAIL` options can be left out:
|
|
|
|
|
|
```
|
|
```
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
docker run -tp 8080:80 -p 8443:443 \
|
|
-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 \
|
|
registry.istandaarden.nl/kik-v/volt/decentral:<version>
|
|
registry.istandaarden.nl/kik-v/starter/decentral:<version>
|
|
```
|
|
```
|
|
|
|
|
|
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 `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_HOSTNAME` and the appropriate email in `KIK_EMAIL` to request and use a new certificate instead. |
|
\ No newline at end of file |
|
|