Skip to content

Opleverdocument

Inleiding

Dit document is bedoeld om de applicatie lokaal of op een productieomgeving te configureren. Het document bevat de stappen die nodig zijn om de applicatie te laten draaien op een lokale omgeving, en de stappen die nodig zijn om de applicatie te laten draaien op een productieomgeving. Verder zijn ook de afhankelijkheden van het product en de belangrijke keuzes die gemaakt zijn in dit document opgenomen.

1. Lokale ontwikkelomgeving opzetten

1.1 Pre-requisites

  1. Docker
  2. 1Password CLI
  3. Ngrok
  4. Database manager (bijv. MySQL Workbench, Azure Data Studio, DataGrip, etc.)

Zorg dat je de 1Password CLI hebt geïnstalleerd en dat je bent ingelogd. Dit is nodig om de geheime waarden uit de 1Password vault te halen.

Zorg ook dat je in Docker een container van MariaDB hebt draaien.

Optioneel, ngrok tunnel

Voor het resetten van de branch in de applicatie wordt er een webhook verstuurd, om deze lokaal ook te ontvangen is het handig om Ngrok te gebruiken. Hiermee kun je een tunnel maken naar je localhost. Dit is niet verplicht, je kan ook de branch handmatig naar null zetten in het bijbehorende project in de database wanneer je de branch van de vertalingen verwijdert hebt.

1
ngrok http https://localhost:44300

Installatie

  • Clone de repository
  • Voer het volgende commando uit in de root van de repository
1
2
# in de root /
yarn install-all
  • appsettings.json secrets genereren

Let op

Zorg dat je de 1Password CLI hebt geïnstalleerd en dat je bent ingelogd.

1
2
3
cd api.pmp.nl
# in /api.pmp.nl
yarn injectSecrets:dev
  • local appsettings.json aanmaken

Kopieer appsettings.Local.Example.json naar appsettings.Local.json en vul de gegevens in.

Ngrok main application url

Als je Ngrok gebruikt, zorg dan dat je de URL van Ngrok in de appsettings.Local.json zet. Anders kun je deze configuratie weghalen.

  • Voorbereiding end-to-end tests
1
2
# in /api.pmp.nl
yarn pretest
  • Google Cloud credentials instellen

De cloud credentials kunnen via de command line aangemaakt worden, deze staan ook in de 1Password production vault. klik hier om credentials aan te maken

In de appsettings.Local.json kun je vervolgens het pad naar de credentials instellen.

  • Opstarten server

Zorg dat de database in docker aan het draaien is, en dat je de juiste connection strings in de appsettings.Local.json hebt gezet.

  • Opstarten client
1
2
# in de client folder /web.pmp.nl
yarn start

Success

De sever en de client zouden nu succesvol op moeten starten.

Aanmaken admin account & project

Om een admin account aan te maken, kun je de volgende stappen volgen:

Account aanmaken

  1. Open de API in je editor naar keuze, en open Api.Pmp.Nl/Controllers/AdminController.cs
  2. Zet of comment de regel [ApiExplorerSettings(IgnoreApi = true)] bij de AddFullAsync methode uit
  3. Ga naar https://localhost:3000/swagger
  4. Open de Admin controller en de AddFullAsync methode
  5. Voer de gegevens in en druk op Execute
  6. Het account is nu aangemaakt

Project aanmaken

  • Open je database manager en maak een connectie met de database
  • Voer de volgende query uit:
1
2
INSERT INTO Project (Id, Name, Created, Changed) 
VALUES ('<guid>', '<naam>', NOW(), NOW())

2. Productieomgeving opzetten

  1. Ga naar de GitLab omgeving
  2. Selecteer het project Project Management Portal
  3. Ga naar Operate > Environments
  4. Maak de "environment" aan, geef deze een logisch naam (bijvoorbeeld, production, staging, test, accept, etc.`). Je hoeft alleen de naam in te vullen.
  5. Ga naar Settings > CI/CD > Variables
  6. Zorg dat de 1Password service account token (OP_SERVICE_ACCOUNT_TOKEN) bij de nieuwe environment kan, mogelijk dat hiervoor nog een nieuwe vault voor aan gemaakt moet worden.
  7. Zorg dat de variabele Protected, Masked en Expanded is.
  8. Zorg dat je in RootNet een project hebt aangemaakt en houdt de juiste variabelen bij de hand.
  9. Open je code editor en open gitlab-ci.yml
  10. Maak de variabelen aan voor de omgeving die je bij de hand hebt gehouden van RootNet. 
    1
2
3
    <environment>_PROJECT: ""
<environment>_SERVER: ""
<environment>_ARCHIVE: ""
  11. Maak voor de omgeving een nieuwe build en deploy job aan, zorg dat de job alleen uitgevoerd wordt als de branch de bijbehorende branch van de omgeving is, en de environment gelijk is aan de naam die je eerder gekozen hebt.
  12. Pas de variabelen in beide jobs aan naar de variabelen die je net hebt aangemaakt.

Success

Wanneer er naar de gekoppelde branch gemerged wordt, zal er een nieuwe build en deploy job aangemaakt worden. De applicatie zal nu draaien in de omgeving die je hebt aangemaakt.

3. Afhankelijkheden product

Het product is afhankelijk van de volgende tools:

  1. Azure DevOps API
  2. GitLab API
  3. 1Password CLI (alleen voor de app settings configuratie)
  4. Google Cloud Translation API
  5. Bunny CDN API

4. Belangrijke keuzes

Zie alle technische en functionele keuzes in de use cases onder het technisch en functioneel ontwerp, met toevoeging van de technisch keuzes die in het technisch ontwerp staan.

4.1 Bestandsstructuur vertalingen

De applicatie gebruikt regex om de vertalingsbestanden te identificeren, dit betekent dat de tool afhankelijk is van de bestandsstructuur. De paden van het volgende voorbeeld zijn correct:

De foldernamen maken niet uit, het gaat slechts om de bestandsstructuur.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
*/Resources
    /SharedResource.resx
    /SharedResource.nl.resx
    /SharedResource.en-US.resx
*/MessageTemplates
    /nl
        /notificationReminder.scriban
    /passwordReset
        /passwordReset.nl.scriban
    /passwordReset
        /passwordReset.en-US.scriban
*/i18n
    /nl
        /common.json
        /admin.json
        /navigation.json
    /en-US
        /common.json
        /admin.json
        /navigation.json

Voorbeeld van incorrect paden:

Info

De volgende paden zouden altijd toegevoegd kunnen worden als ondersteuning door de regex aan te passen. Een andere optie is om per project een configuratie bestand te maken waarin de paden van de vertalingsbestanden worden opgeslagen, die mogelijk ook via de front-end te configureren is. Een ander alternatief is om het project dat beheert wordt aan te passen zodat deze bestandsstructuur ondersteund wordt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
*/Resources
    /Resource.resx
    (Geen vertalingsversies)
*/MessageTemplates
    /nl
        /passwordReset
            /mail.scriban
*/components
    /Component1
        /translations
            /nl.json