title	date	weight
Aan de slag	25-02-2019	100

De referentie componenten kunnen gebruikt worden door ontwikkelaars in hun eigen ontwikkelomgeving om bijvoorbeeld vakapplicaties te testen, of een ontbrekend component in de eigen software te simuleren.

Snelle start

Al bekend met alle vereisten en de opzet? Hieronder de commando's om snel van start te gaan. Ga anders naar de Voorbereiding.

$ git clone git@github.com:VNG-Realisatie/gemma-zaken.git
$ cd gemma-zaken/infra
$ docker-compose pull
$ docker-compose up

Voorbereiding

Alle referentie componenten zijn als Docker containers beschikbaar. De volgende onderdelen zijn nodig om aan de slag te gaan:

Verplicht

Docker
- Windows (Docker Toolbox, indien Virtualbox moet blijven werken)
- Windows (Docker for Windows, als Virtualbox niet belangrijk is)
- MacOS (Docker for Mac)
- Linux (Docker for Linux)
Docker Compose (alleen niet inbegrepen bij Docker for Linux)
- Linux

Docker for Windows werkt alleen op Windows 10 Professional

Optioneel

Git (handig om snel updates binnen te halen)

Referentie componenten opstarten

Clone de VNG-Realisatie/gemma-zaken repository op de eigen computer:
```
git clone git@github.com:VNG-Realisatie/gemma-zaken.git
```
Of, gebruik git clone https://github.com/VNG-Realisatie/gemma-zaken.git als authenticatie een issue is.

Of, download de repository handmatig en pak deze uit in de gemma-zaken folder.
Navigeer naar de infra folder in deze repository.
- Voor MacOS, Linux en Windows (met Docker for Windows):
```
$ cd gemma-zaken/infra
```
- Voor Windows (met Docker Toolbox):
  1. Start de Docker Quickstart Terminal vanuit het Start menu.
  2. Navigeer naar de folder waar de repository staat. Als deze bijvoorbeeld staat in C:\Projecten\gemma-zaken gaat dat als volgt:
```
$ cd /C/Projecten/gemma-zaken
$ cd infra
```

Start de referentie componenten:

$ docker-compose pull  # update naar nieuwste versie
$ docker-compose up

Vind en gebruik het juiste IP:
- Voor MacOS en Linux:
  
  Alle containers zijn bereikbaar op localhost of 127.0.0.1.
- Voor Windows (met Docker for Windows):
  
  Het beste is om het NAT IP te gebruiken in plaats van localhost. Deze laatste kan soms problemen geven als een proces vanuit een Docker container met een andere Docker container wil communiceren.
  
  In een shell, voer ipconfig uit en zoek naar DockerNAT:
```
$ ipconfig
...
Ethernet adapter vEthernet (DockerNAT):
   Connection-specific DNS Suffix  . :
   IPv4 Address. . . . . . . . . . . : 10.0.75.1
   Subnet Mask . . . . . . . . . . . : 255.255.255.0
   Default Gateway . . . . . . . . . :
```
  Alle containers zijn bereikbaar op 10.0.75.1.
- Voor Windows (met Docker Toolbox):
  
  Docker Toolbox werkt iets anders en de referentie componenten zijn niet op localhost bereikbaar. In plaats daarvan moet het Docker VM IP-adres gebruikt worden:
```
$ docker-machine ip
192.168.99.100
```
Alle containers zijn bereikbaar op 192.168.99.100.
Bevraag de APIs via de browser.

De componenten zijn bereikbaar op verschillende poorten op het IP uit de vorige stap.

Navigeer in de browser naar:
- ZRC: http://<ip>:8000
- DRC: http://<ip>:8001
- ZTC: http://<ip>:8002
- BRC: http://<ip>:8003
- NRC: http://<ip>:8004
Admin aanmaken voor elk referentie component

Elk referentie componenent heeft een beheer interface. Om deze beheer interface te benaderen, moet een gebruiker worden aangemaakt (voorbeeld voor het ZTC):
```
$ docker container ls
CONTAINER ID    ...      PORTS                    NAMES
2bea81c01aea    ...      0.0.0.0:8000->8000/tcp   infra_zrc_web_1
e1638c2da098    ...      0.0.0.0:8003->8000/tcp   infra_brc_web_1
...
$ docker exec -it infra_ztc_web_1 /app/src/manage.py createsuperuser
...
```
In plaats van infra_ztc_web_1 kunnen ook de andere Docker containers benaderd worden door de bewuste naam onder NAMES te gebruiken.

Vervolgens kan je daarmee inloggen op http://<ip>:800x/admin/ om testdata in te kunnen richten of gegevens te raadplegen.
Indien extra configuratie nodig is binnen een component, dan vind je deze in de documentatie van de component zelf. Deze staat gelinkt op http://<ip>:800x indien die aanwezig is.
De volgende stap is het inrichten van de autorisaties

Inrichten autorisaties

De componenten maken gebruik van tokens om van autorisatie op de hoogte te zijn. Een consumer praat tegen een provider, op voorwaarde dat een geldig token meegegeven is. Providers kunnen op hun beurt ook weer consumers zijn van andere providers, en die dienen ook valide tokens te gebruiken.

Beide vormen gebruiken hetzelfde mechanisme.

Een consumer moet rechten hebben om bepaalde data op te vragen. Hiertoe dienen zowel de provider en als de consumer een gedeeld secret te hebben. Aan de hand van de Identifier is bekend welke consumer het betreft.

Autorisatie inrichten voor consumers

Login op de admin en ga naar Jwt secrets en klik op Toevoegen.

Vul alle gegevens in en klik op Opslaan:
- Identifier: Een willeurige string, bijvoorbeeld demo.
- Secret: Een willekeurige string, bijvoorbeeld demo.
Dit zijn de credentials om straks een JWT aan te maken, waarvan zowel de consumer als de provider het secret kennen. Dit moet typisch op elk component gebeuren. Het maakt niet uit wat wordt ingevuld maar het eenvoudigst is als in alle componenten hetzelfde wordt ingevuld.
Autorisaties regelen tussen componenten

Het ZRC moet typisch een Zaaktype valideren in het ZTC. Hiervoor moet het ZRC wel toestemming hebben om het ZTC te bevragen.

Login op de ZRC admin en ga naar API credentials en klik op Toevoegen.

Hier wordt geconfigureerd welke credentials bij welke URLs/URL-prefixes horen.

Vul alle gegevens in en klik op Opslaan:
- Api root: Vul hier de URL in van de API root van het betreffende "andere" component. Bijvoorbeeld: http://<ip>:800x/api/v1/
- Client id: Vul hier hetzelfde in als de Identifier in stap 1 voor het betreffende component wat bereikbaar is op Api root.
- Secret: Vul hier hetzelfde in als de Secret in stap 1 voor het betreffende component wat bereikbaar is op Api root.
De componenten maken zo onderling gebruik van dezelfde secrets als een consumer maar dat is niet erg voor test doeleinden.
JWT aanmaken

Navigeer naar: https://ref.tst.vng.cloud/tokens/generate-jwt/

Vul de Identifier en Secret in van stap 1, de relevante scopes en zaaktypes, en klik op Bevestig.

Er wordt nu een JWT gegenereerd die gebruikt kan worden in de Authorization header. Om het JWT te inspecteren kan je deze (zonder Bearer) plakken op jwt.io. Overigens kunnen de zaakypes vervangen worden met de array ["*"] voor alle zaaktypes. Vergeet niet om je eigen secret (onderin rechts) in te vullen i.p.v. your-256-bit-secret!

Het aanmaken van een JWT registreert het secret niet bij de gehoste referentie componenten. Zie de API guides hoe dit wel werkt.

En verder...

Referentie componenten stoppen

De referentie componenten draaien op de achtergrond. Om geen onnodige resources te gebruiken op de computer kunnen ze eenvoudig weer uitgezet worden:

$ docker-compose down

APIs benaderen

De API's en API documentatie zijn beschikbaar op de volgende URLs:

http://localhost:800x/api/v1/ - API root
http://localhost:800x/api/v1/schema/ - API documentatie

API Guides

Er zijn verschillende API guides beschikbaar met veelvoorkomende consumer handelingen.

Poorten wijzigen

Bridge network

De default docker-compose setup gebruikt de bridge network mode. Een groot nadeel hiervan is dat URLs in requests/responses met localhost:800x binnen containers niet kunnen geresolved worden, wat leidt tot (obscure) validatiefouten.

Indien je Docker for Windows gebruikt, kan je hier omheen werken door de componenten niet via localhost te benaderen, maar via een IP-adres.

Open een shell, en voer uit:

> ipconfig

Ga op zoek naar het DockerNAT netwerk - daar staat een gateway (10.x.y.1) normaal. De componenten zouden moeten bereikbaar zijn op:

10.x.y.2:8000
10.x.y.2:8001
10.x.y.2:8002
10.x.y.2:8003
10.x.y.2:8004

Host network

Er is een alternatieve setup die gebruik maakt van de host network mode. Dit zorgt ervoor dat containers met elkaar kunnen verbinden, ook als URLs naar localhost verwijzen (zie #537).

Gebruik:

$ docker-compose -f docker-compose.yml -f docker-compose.hostnetwork.yml up

De -f optie specifieert welke config files voor docker-compose gebruikt moeten worden.

Het nadeel hiervan is dat de database en webservices poorten in gebruik nemen op je lokale machine. Concreet gaat het om:

5436, 8000 voor het ZRC
5437, 8001 voor het DRC
5438, 8002 voor het ZTC
5439, 8003 voor het BRC
5440, 8004 voor het NRC

Je kan deze poorten aanpassen, indien gewenst. Dit doe je door een bestand .env aan te maken in de map infra (=zelfde locatie waar je docker-compose up uitvoert).

De inhoud hiervan is (met de defaults):

ZRC_DB_PORT=5436
ZRC_UWSGI_PORT=8000

DRC_DB_PORT=5437
DRC_UWSGI_PORT=8001

ZTC_DB_PORT=5438
ZTC_UWSGI_PORT=8002

BRC_DB_PORT=5439
BRC_UWSGI_PORT=8003

NRC_DB_PORT=5440
NRC_UWSGI_PORT=8004

Je kan zelf de vrije poortnummers invullen die je wenst te gebruiken. Je hoeft enkel de poorten op te geven die je wil wijzingen - indien variabelen ontbreken wordt op de defaults teruggevallen.

Eerste hulp

De componenten kunnen elkaar niet bereiken

Helaas een bekend probleem onder Windows. Achterliggende oorzaak is dat als een component via Docker bereikbaar is op localhost

Niet alle componenten zijn bereikbaar

Bekijk de status van de Docker containers:

$ docker container ls --all

Zijn er één of meerdere containers met de status Exited? Dan gaat er iets niet goed.

In dit stadium van de referentie componenten kan het voorkomen dat er niet goed gemigreerd wordt van een oude naar een nieuwe versie, of dat er ergens iets stuk is gegaan. Wat mogelijk helpt is alle oude data te verwijderen en de referentie componenten opnieuw te installeren:

$ docker-compose down
$ docker system prune  # Verwijdert alles behalve data!
$ git pull
$ docker-compose pull
$ docker-compose up

Foutmelding: Error starting userland proxy / driver failed

Soortgelijke foutmeldingen gebeuren af en toe bij het starten van de Docker containers. Een mogelijke oplossing:

$ docker-compose down

En herstart Docker. Het kan soms voorkomen dat het herstarten alleen een oplossing biedt als er verbonden is met een netwerk zodat een publiek IP gebruikt kan worden. Nadat docker opnieuw is opgestart

$ docker-compose up

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

aan-de-slag.md

aan-de-slag.md

Snelle start

Voorbereiding

Referentie componenten opstarten

Inrichten autorisaties

En verder...

Referentie componenten stoppen

APIs benaderen

API Guides

Poorten wijzigen

Bridge network

Host network

Eerste hulp

De componenten kunnen elkaar niet bereiken

Niet alle componenten zijn bereikbaar

Foutmelding: Error starting userland proxy / driver failed

Files

aan-de-slag.md

Latest commit

History

aan-de-slag.md

File metadata and controls

Snelle start

Voorbereiding

Referentie componenten opstarten

Inrichten autorisaties

En verder...

Referentie componenten stoppen

APIs benaderen

API Guides

Poorten wijzigen

Bridge network

Host network

Eerste hulp

De componenten kunnen elkaar niet bereiken

Niet alle componenten zijn bereikbaar

Foutmelding: Error starting userland proxy / driver failed