EAM Explorer — Azure Implementatiegids

↗

Architectuur & principes

De EAM Explorer bestaat uit twee onderdelen in één Docker image:

Vue 3 SPA — statische bestanden gebouwd met Vite
Node.js proxy — Express-server die de EAM API-sleutel server-side toevoegt

🔑

Beveiligingsprincipe: de EAM_KEY (X-API-Key) verlaat de server nooit. De browser ziet hem niet. De proxy voegt hem server-side toe aan elk verzoek naar Hexagon EAM. Dit principe moet bij alle deployment-varianten gehandhaafd blijven.

De EAM-host is https://eu1.eam.hxgnsmartcloud.com voor de EU-cloud van Hexagon. De container maakt outbound HTTPS-verbindingen naar dit adres — zorg dat uitgaand verkeer op poort 443 niet geblokkeerd wordt.

⚖

Aanbevolen Azure-service

Service	Geschikt voor	SSL	VNet	Complexiteit
App Service for Containers ✓	Standaard productie-deployments	Ingebouwd	Met VNet Integration	Laag
Container Apps	Meerdere klanten, auto-scaling	Ingebouwd	Met environment VNet	Middel
Azure VM + Docker	Maximale controle	Zelf regelen	Standaard	Hoog

Aanbeveling: Azure App Service for Containers. SSL, custom domein en omgevingsvariabelen zijn ingebouwd. Geen nginx of PM2 nodig. Geschikt voor de meeste klanten, inclusief overheidsinstanties mits gecombineerd met VNet Integration (zie sectie Overheid).

⚠

Kies minimaal de B1-tier (Basic). De gratis F1-tier heeft geen custom domain support en beperkte uptime-garantie.

1

Azure Container Registry aanmaken

Maak een privé Container Registry aan in de Azure-omgeving van de klant. Het Docker image wordt hier opgeslagen zodat alles binnen het Azure-ecosysteem blijft.

Via Azure CLI

AZURE CLI
# Resourcegroep aanmaken (eenmalig)
az group create \
  --name rg-eam-explorer \
  --location westeurope

# Container Registry aanmaken (Basic tier volstaat)
az acr create \
  --resource-group rg-eam-explorer \
  --name klantnaamacr \
  --sku Basic \
  --admin-enabled true

# Inloggegevens ophalen (nodig voor GitLab CI/CD)
az acr credential show \
  --name klantnaamacr

De uitvoer geeft een username en twee passwords. Bewaar deze voor stap 2.

💡

De registry-naam (klantnaamacr) moet globaal uniek zijn op .azurecr.io. Kies een naam als eamclientnaam. De login-server wordt dan eamclientnaam.azurecr.io.

2

GitLab CI/CD aanpassen

Voeg de ACR-gegevens toe als GitLab CI/CD-variabelen en maak een extra build-job die het image naar de ACR pusht.

GitLab variabelen toevoegen

Ga naar GitLab → Settings → CI/CD → Variables en voeg toe:

Variabele	Waarde	Protected
`ACR_REGISTRY`	`klantnaamacr.azurecr.io`	Nee
`ACR_USERNAME`	username uit stap 1	Nee
`ACR_PASSWORD`	password uit stap 1	Ja — masked

Aanvulling op .gitlab-ci.yml

Voeg een aparte job toe voor de Azure-productie-build. Let op: voor App Service draait de app op het root-pad (/), niet op een subpad zoals /prod/.

.GITLAB-CI.YML — extra job
# Bouwt een image voor klant-Azure deployment (VITE_BASE_PATH=/ → root)
build_azure:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_BUILDKIT: "1"
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker login -u $ACR_USERNAME -p $ACR_PASSWORD $ACR_REGISTRY
  script:
    - docker build
        --build-arg VITE_BASE_PATH=/
        --tag $CI_REGISTRY_IMAGE:azure
        --tag $ACR_REGISTRY/eam-explorer:latest
        .
    - docker push $CI_REGISTRY_IMAGE:azure
    - docker push $ACR_REGISTRY/eam-explorer:latest
  only:
    - main
  when: manual

⚠

VITE_BASE_PATH=/ is essentieel voor App Service. De app draait op de root van het domein (https://eam.klant.nl/), niet op een subpad. Als je het image van de VPS-pipeline hergebruikt (gebouwd met /prod/), werkt de asset-routing niet.

3

Azure App Service aanmaken

Via Azure CLI

AZURE CLI
# App Service Plan (Linux, minimaal B1)
az appservice plan create \
  --name plan-eam-explorer \
  --resource-group rg-eam-explorer \
  --is-linux \
  --sku B1

# Web App for Containers aanmaken
az webapp create \
  --resource-group rg-eam-explorer \
  --plan plan-eam-explorer \
  --name eam-explorer-klant \
  --deployment-container-image-name \
    klantnaamacr.azurecr.io/eam-explorer:latest

# ACR koppelen (zodat App Service kan pullen)
az webapp config container set \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --docker-registry-server-url https://klantnaamacr.azurecr.io \
  --docker-registry-server-user $ACR_USERNAME \
  --docker-registry-server-password $ACR_PASSWORD

Poort configureren

AZURE CLI
az webapp config appsettings set \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --settings WEBSITES_PORT=3000

Automatisch herladen bij nieuw image

AZURE CLI
# App Service herstart automatisch bij nieuwe push naar ACR
az webapp deployment container config \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --enable-cd true

4

Omgevingsvariabelen instellen

In plaats van een .env-bestand op de server worden alle variabelen ingesteld als App Service Application Settings. Azure versleutelt deze at rest.

Variabele	Waarde	Gevoelig
`PORT`	`3000`
`EAM_HOST`	`https://eu1.eam.hxgnsmartcloud.com`
`EAM_TENANT`	bijv. `KLANT_PRD`
`EAM_ORG`	bijv. `ENN` of `*`
`EAM_KEY`	API-sleutel uit EAM Integration Configuration	✓ Zie tip
`GRID_STRUCTURES_NAME`	`XUSTRU`
`WEBSITES_PORT`	`3000`

AZURE CLI — alle variabelen in één commando
az webapp config appsettings set \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --settings \
    PORT=3000 \
    WEBSITES_PORT=3000 \
    EAM_HOST="https://eu1.eam.hxgnsmartcloud.com" \
    EAM_TENANT="KLANT_PRD" \
    EAM_ORG="*" \
    EAM_KEY="jouw-api-sleutel-hier"

🔐

Aanbeveling voor EAM_KEY: sla de API-sleutel op in Azure Key Vault en verwijs ernaar vanuit App Settings als @Microsoft.KeyVault(SecretUri=...). De sleutel staat dan nooit in plaintext in de portal. Dit is standaardpraktijk bij overheidsinstanties.

5

Custom domein & SSL

App Service levert gratis een *.azurewebsites.net-domein met SSL. Voor een eigen domein (bijv. eam.klant.nl) zijn twee stappen nodig.

DNS-record toevoegen bij de klant

DNS — CNAME-record
# Voeg toe bij de DNS-provider van de klant:
eam.klant.nl.  CNAME  eam-explorer-klant.azurewebsites.net.

Domein koppelen en certificaat aanmaken

AZURE CLI
# Domein toevoegen
az webapp config hostname add \
  --webapp-name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --hostname eam.klant.nl

# Gratis beheerd certificaat aanmaken (automatische verlenging)
az webapp config ssl create \
  --resource-group rg-eam-explorer \
  --name eam-explorer-klant \
  --hostname eam.klant.nl

💡

Het gratis App Service-certificaat verlengt automatisch. Er is geen Certbot of eigen TLS-beheer nodig.

Resulterende EAM custom tab URL

EAM CUSTOM TAB URL
https://eam.klant.nl/?tenant=KLANT_PRD&user={{obj_user}}&org={{obj_org}}&equipment={{obj_code}}

§

Overheidsinstanties — extra vereisten

VNet Integration (uitgaand verkeer)

Als de organisatie eist dat uitgaand verkeer via hun eigen netwerk loopt (bijv. voor DLP of egress-filtering), koppel App Service aan een Virtual Network:

AZURE CLI — VNet Integration
# Vereist minimaal Standard-tier App Service Plan
az webapp vnet-integration add \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --vnet vnet-naam \
  --subnet subnet-naam

# Alle uitgaand verkeer via VNet sturen (inclusief naar HxGN Cloud)
az webapp config appsettings set \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer \
  --settings WEBSITE_VNET_ROUTE_ALL=1

Private Endpoint (inkomend verkeer)

Als de EAM Explorer alleen bereikbaar mag zijn vanuit het interne netwerk (niet via internet), gebruik dan een Private Endpoint:

AZURE CLI — Private Endpoint
az network private-endpoint create \
  --name pe-eam-explorer \
  --resource-group rg-eam-explorer \
  --vnet-name vnet-naam \
  --subnet subnet-naam \
  --private-connection-resource-id \
    $(az webapp show --name eam-explorer-klant \
      --resource-group rg-eam-explorer --query id -o tsv) \
  --group-id sites \
  --connection-name conn-eam-explorer

Azure Key Vault voor EAM_KEY

AZURE CLI — Key Vault
# Key Vault aanmaken
az keyvault create \
  --name kv-eam-explorer \
  --resource-group rg-eam-explorer \
  --location westeurope

# API-sleutel opslaan
az keyvault secret set \
  --vault-name kv-eam-explorer \
  --name EAM-KEY \
  --value "jouw-api-sleutel"

# Managed Identity voor App Service inschakelen
az webapp identity assign \
  --name eam-explorer-klant \
  --resource-group rg-eam-explorer

# App Service toegang geven tot Key Vault
az keyvault set-policy \
  --name kv-eam-explorer \
  --object-id $(az webapp identity show \
    --name eam-explorer-klant \
    --resource-group rg-eam-explorer \
    --query principalId -o tsv) \
  --secret-permissions get

Stel daarna in App Settings in:

APP SETTING — Key Vault referentie
EAM_KEY = @Microsoft.KeyVault(VaultName=kv-eam-explorer;SecretName=EAM-KEY)

Diagnostische logboeken (audit)

AZURE CLI — Log Analytics
# Stuur App Service logs naar Log Analytics (SIEM-integratie)
az monitor diagnostic-settings create \
  --name diag-eam-explorer \
  --resource $(az webapp show --name eam-explorer-klant \
    --resource-group rg-eam-explorer --query id -o tsv) \
  --logs '[{"category":"AppServiceHTTPLogs","enabled":true}]' \
  --workspace log-analytics-workspace-id

✓

Implementatie-checklist

○ Azure resourcegroep aangemaakt
○ Azure Container Registry aangemaakt en admin ingeschakeld
○ GitLab CI/CD-variabelen ACR_REGISTRY, ACR_USERNAME, ACR_PASSWORD ingesteld
○ GitLab build_azure-job handmatig uitgevoerd; image in ACR zichtbaar
○ App Service Plan aangemaakt (Linux, minimaal B1)
○ Web App for Containers aangemaakt en gekoppeld aan ACR
○ WEBSITES_PORT=3000 ingesteld
○ EAM_HOST, EAM_TENANT, EAM_ORG, EAM_KEY ingesteld
○ /api/health endpoint geeft 200 OK terug
○ DNS-record aangemaakt en custom domein gekoppeld
○ Beheerd SSL-certificaat aangemaakt
○ EAM custom tab URL getest met ?tenant= en ?user= parameters
○ (Overheid) VNet Integration geconfigureerd
○ (Overheid) EAM_KEY opgeslagen in Key Vault
○ (Overheid) Diagnostische logboeken gekoppeld aan Log Analytics

✅

Na het doorlopen van de checklist is de EAM Explorer bereikbaar via het eigen domein van de klant, volledig beheerd door Azure, zonder dat de EAM API-sleutel de server verlaat.

EAM Explorer draaien op Azure

Architectuur & principes

Aanbevolen Azure-service

Azure Container Registry aanmaken

Via Azure CLI

GitLab CI/CD aanpassen

GitLab variabelen toevoegen

Aanvulling op .gitlab-ci.yml

Azure App Service aanmaken

Via Azure CLI

Poort configureren

Automatisch herladen bij nieuw image

Omgevingsvariabelen instellen

Custom domein & SSL

DNS-record toevoegen bij de klant

Domein koppelen en certificaat aanmaken

Resulterende EAM custom tab URL

Overheidsinstanties — extra vereisten

VNet Integration (uitgaand verkeer)

Private Endpoint (inkomend verkeer)

Azure Key Vault voor EAM_KEY

Diagnostische logboeken (audit)

Implementatie-checklist