Gebruikershandleiding Nessie, Gebruikershandleiding Admin, Server inrichting

De documentatie is opgedeeld in drie delen, allereerst is er de documentatie van Nessie, per tabblad beschrijven we wat je ziet en wat de mogelijkheden zjn.

De gebruikershandleiding is voornamelijk gericht op het gebruik van de tooling via de website.

De overige documenten bevatten gecombineerde informatie over gebruik en inrichting van de server, Nessie en de toolkit.

Server

De server is een Debian-linux machine, er zijn drie gebruikers: root (can't login), kc-xbrl (has super powers), xiffy (yup that's me).

Uitgebreide beschrijving in: server

XBR Toolkit API server (python)

De API server is de interface tussen de toolkit en clients. Op dit moment is Nessie en de bijbehorende admin de belangrijkste client. De API server wordt vanuit /app/kenniscentrumxbrl opgestart. De beste methode is:

/app/kenniscentrumxbrl$ make toolkit

Dit commando haalt eerst de nieuwste versie van de toolkit uit gitlab, en vervolgens wordt de API Server herstart. Dit is dus ook het commando dat je aanroept wanneer je programmawijzigingen live wilt zetten.

Uitgebreide beschrijving in: XBRL toolkit

XBRL Taxonomy viewer (Nessie)

Nessie is geschreven met behulp van Quasar, wat weer een schil om Vue heen is. De applicatie wordt als statische html, css en een berg javascript aan de client geserveerd. Builden doe je in /app/nessie-quasar

Om de applicatie te updaten ga je als volgt te werk:

/app/nessie-quasar$ make nessie

Dit commando haalt eerst de laatste versie van de source van gitlab. Vervolgens wordt de applicatie gebuild, waarna de build in /var/www/html wordt gekopieerd. De client krijgt nu de nieuwe applicatie. (Maar niet als browser-cache in de weg zit)

Voor een uitgebreide beschrijving zie: XBRL Taxonomy viewer

validatierapporten

Bij het parsen van taxonomieen bestaat de mogelijkheid om validatierapporten te schrijven. Deze rapporten zijn de uitkomst van het controleren van de aangeboden taxonomie tegen de NTA-regels. De validatierapporten worden geschreven tijdens het gebruik van de admin en komen vanzelf op de juiste locatie terecht. De rapporten zijn beschikbaar op de webserver en bereikbaar vanuit Nessie door op de naam van het entrypoint in de header te klikken.

Vergelijkingen tussen NTA versies

De toolkit kan, als de taxonomieen zijn opgeslagen in de database versierapporten produceren. We vergelijken dan de verschillende onderdelen van de taxonomie en rapporteren alle objecten die wel in de nieuwste, maar niet in de vorige versie aanwezig zijn. Vanuit deze rapporten linken we naar Nessie om zo meer inzicht in het (ver)nieuw(d)e object te krijgen. Voor uitgebreide beschrijving zie: Versierapporten

nta-regels

De NTA-Regels worden door Logius beheerd. Dat gebeurde in een WiKi, en dat is herschreven naar een ReSpec-formaat. Ik zeg bewust formaat, want de site wordt gegenereerd uit een groot aantal JSON bestanden, één voor elke regel. De regels en het beheertool zijn nu op de server geplaats. Voor uitgebreide beschrijving zie: NTA Regels

nginx

Alle communicatie naar buiten gaat via nginx. Nginx is supersnel, werkt goed met SSL (https) en kan responses cachen. De routing van de verschillende requests gaat via de configuratie. Cache-duur, grootte van de cache en bestandlocaties wordt hier allemaal geregeld. Bestanden: /etc/nginx/nginx.conf en /etc/nginx/sites-enables/00-kc-xbrl. Voor uitgebreide beschrijving zie: Nginx.

goaccess

We gebruiken GoAccess om rudimentaire statistiek van de webserver te krijgen. We gebruiken hier de nginx accesslogs voor. Dus geen Google Anlytics e.d. Je mist daardoor een heleboel informatie, maar je krijgt enigzins een inzicht in het bezoek aan de website. De statistiek is openbaar te zien. Momenteel start ik goaccess als volgt op:

sudo goaccess --exclude-ip 2a01:7c8:d007:209:5054:ff:fe8b:f34b --daemonize --anonymize-ip -H no -q

Waarbij we localhost negeren (ip-nummer), een http-requests op poort 80 ook. We tellen alleen https (-H) en de querystring negeren we om performance redenen (-q). De configuratie staat in /etc/goaccess/goaccess.conf, daarin is onder andere geconfigureerd dat de gegevens moeten worden opgeslagen (in /var/cache/goaccess/) en teruggelezen bij een herstart. Een herstart van goaccess doe je als volgt:

sudo pkill goaccess
sleep 5
sudo goaccess --exclude-ip 2a01:7c8:d007:209:5054:ff:fe8b:f34b --daemonize --anonymize-ip -H no -q

Gebruik --html-prefs {hosts:{active:false}} als je helemaal geen hosts wilt zien. Op deze manier kan je ook andere panelen uitschakelen.

Documentatie

De documentatie (o.a. dit document) is een klein project op zichzelf. Voor uitgebreide beschrijving zie: Documentatie

Release notes

Een voorzichtige start van de Release Notes