Guide d’auto-hébergement de Browserless Thunders

Vue d’ensemble

L’image Thunders Browserless est un conteneur unifié qui regroupe :

Browserless Enterprise — Moteur de navigateur headless prenant en charge Chromium, Firefox et WebKit
Proxy inverse Nginx — Routage des requêtes, proxy WebSocket, health checks et distribution de fichiers
Pont Azure Relay — Connexion sortante uniquement à Azure Relay pour une communication sécurisée avec la plateforme Thunders

Ces trois composants tournent dans un seul conteneur, géré par supervisord, ce qui rend le déploiement simple.

Comment ça fonctionne

Points clés :

Aucune règle de pare-feu entrante requise — Le pont relay se connecte en sortie à Azure Relay via HTTPS (port 443)
Pas de VPN — Azure Relay gère le tunnel sécurisé
Un seul conteneur — Une seule image à récupérer, un seul conteneur à exécuter

Prérequis

Un abonnement Azure (ou tout environnement capable d’exécuter des conteneurs Docker)
Des identifiants ACR fournis par Thunders (pour récupérer l’image)
Une configuration Azure Relay (voir la section Azure Relay ci-dessous)
Pour les déploiements Azure : Azure CLI installé et authentifié

Identifiants que vous recevrez de Thunders

Thunders vous fournira les identifiants suivants pour votre déploiement :

Identifiant	Description
Serveur ACR	URL du registre de conteneurs (ex. `youracr.azurecr.io`)
Nom d’utilisateur ACR	Nom du jeton pour récupérer l’image
Mot de passe ACR	Mot de passe du jeton
Espace de noms Relay	Espace de noms Azure Relay (si géré par Thunders)
Nom de la connexion hybride Relay	Nom de la hybrid connection (si géré par Thunders)
Clé d’écoute Relay	Clé SAS avec permission d’écoute (si géré par Thunders)

Conservez-les en lieu sûr. Ne les committez jamais dans le code source.

Configuration d’Azure Relay

Azure Relay permet une communication sécurisée entre la plateforme Thunders et votre instance browserless auto-hébergée, sans ouvrir de ports entrants. Il existe deux options :

Option A : Relay géré par Thunders (recommandé)

Thunders crée et gère l’espace de noms Azure Relay et la connexion hybride dans l’abonnement Azure de Thunders. Vous recevrez :

RELAY_NAMESPACE — URL de l’espace de noms Relay
RELAY_HYCO — Nom de la hybrid connection
RELAY_LISTEN_KEY — Clé SAS avec permission d’écoute

Votre conteneur se connecte en sortie à ce relay. La plateforme Thunders se connecte de l’autre côté avec des permissions d’envoi.

Aucune configuration Azure Relay n’est nécessaire de votre côté.

Option B : Relay géré par le client

Si vous préférez gérer le relay dans votre abonnement Azure :

Créer un espace de noms Azure Relay :

az relay namespace create \
  --resource-group <your-rg> \
  --name <relay-namespace-name> \
  --location <azure-region>

2. Créer une hybrid connection :

az relay hyco create \
  --resource-group <your-rg> \
  --namespace-name <relay-namespace-name> \
  --name <hybrid-connection-name>

3. Créer des règles d’autorisation :

Créer une règle listen (pour votre conteneur auto-hébergé) :

az relay hyco authorization-rule create \
  --resource-group <your-rg> \
  --namespace-name <relay-namespace-name> \
  --hybrid-connection-name <hybrid-connection-name> \
  --name listen \
  --rights Listen

Créer une règle send (pour la plateforme Thunders) :

az relay hyco authorization-rule create \
  --resource-group <your-rg> \
  --namespace-name <relay-namespace-name> \
  --hybrid-connection-name <hybrid-connection-name> \
  --name send \
  --rights Send

4. Récupérer les clés :

Obtenir la clé listen (pour votre conteneur) :

az relay hyco authorization-rule keys list \
  --resource-group <your-rg> \
  --namespace-name <relay-namespace-name> \
  --hybrid-connection-name <hybrid-connection-name> \
  --name listen \
  --query primaryKey -o tsv

Obtenir la clé send (à partager avec Thunders) :

az relay hyco authorization-rule keys list \
  --resource-group <your-rg> \
  --namespace-name <relay-namespace-name> \
  --hybrid-connection-name <hybrid-connection-name> \
  --name send \
  --query primaryKey -o tsv

5. Partager avec Thunders :

Espace de noms Relay : .servicebus.windows.net
Nom de la hybrid connection :
Nom de la clé d’envoi : send
Secret de la clé d’envoi : (la clé send de l’étape 4)

Thunders configurera ces éléments dans la plateforme pour se connecter à votre relay.

Référence des variables d’environnement

Variables requises

Variable	Description	Exemple
`RELAY_NAMESPACE`	Espace de noms Azure Relay	`myrelay.servicebus.windows.net`
`RELAY_HYCO`	Nom de la hybrid connection	`thunder-browserless`
`RELAY_LISTEN_KEY`	Clé SAS avec permission d’écoute	`base64-encoded-key`

Variables optionnelles

Variable	Valeur par défaut	Description
`CONCURRENT`	`15`	Nombre maximum de sessions navigateur simultanées
`TIMEOUT`	`1800000`	Timeout de session en millisecondes (par défaut : 30 minutes)
`EXTERNAL`	`http://localhost:3000`	URL externe de cette instance (utilisée dans les réponses de health)

Ports

Port	Service	Description
`3000`	Nginx (exposé)	Point d’entrée principal, health checks, proxy WebSocket
`3001`	Browserless (interne)	Moteur de navigateur (proxy via Nginx)
`3002`	Health check (interne)	Service de calcul du score de santé
`8080`	Pont Relay (interne)	Endpoint de santé du pont Azure Relay

Seul le port 3000 doit être exposé.

Options de déploiement

Option 1 : Azure Container Apps (recommandé)

Azure Container Apps fournit une plateforme managée pour exécuter des conteneurs, avec scaling, sondes de santé et HTTPS.

# Login to Azure
az login

# Set variables
RESOURCE_GROUP="rg-thunder-browserless"
LOCATION="westeurope"
ENV_NAME="env-thunder-browserless"
APP_NAME="thunder-browserless"

# Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

# Create Container Apps environment
az containerapp env create \
  --name $ENV_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION

# Deploy the container app
az containerapp create \
  --name $APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --environment $ENV_NAME \
  --image <THUNDER_ACR_SERVER>/thunder-browserless:latest \
  --registry-server <THUNDER_ACR_SERVER> \
  --registry-username <THUNDER_ACR_USERNAME> \
  --registry-password <THUNDER_ACR_PASSWORD> \
  --target-port 3000 \
  --ingress internal \
  --cpu 4.0 \
  --memory 8.0Gi \
  --min-replicas 1 \
  --max-replicas 1 \
  --env-vars \
    CONCURRENT=15 \
    TIMEOUT=1800000 \
    RELAY_NAMESPACE=<YOUR_RELAY_NAMESPACE> \
    RELAY_HYCO=<YOUR_RELAY_HYCO> \
    RELAY_LISTEN_KEY=secretref:relay-key \
  --secrets \
    relay-key=<YOUR_RELAY_LISTEN_KEY>

Utilisez le template ARM fourni pour un déploiement plus configurable :

az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --template-file customer-browserless-template.json \
  --parameters \
    containerAppName=$APP_NAME \
    containerAppEnvironmentId=$(az containerapp env show -g $RESOURCE_GROUP -n $ENV_NAME --query id -o tsv) \
    containerImage=<THUNDER_ACR_SERVER>/thunder-browserless:latest \
    acrServer=<THUNDER_ACR_SERVER> \
    acrUsername=<THUNDER_ACR_USERNAME> \
    acrPassword=<THUNDER_ACR_PASSWORD> \
    relayNamespace=<YOUR_RELAY_NAMESPACE> \
    relayHycoName=<YOUR_RELAY_HYCO> \
    relayListenKey=<YOUR_RELAY_LISTEN_KEY>

Option 2 : Azure Container Instances (ACI)

Azure Container Instances fournit un hébergement serverless de conteneurs. C’est plus simple, mais avec moins de fonctionnalités que Container Apps.

# Create resource group
az group create --name rg-thunder-browserless --location westeurope

# Deploy container
az container create \
  --resource-group rg-thunder-browserless \
  --name thunder-browserless \
  --image <THUNDER_ACR_SERVER>/thunder-browserless:latest \
  --registry-login-server <THUNDER_ACR_SERVER> \
  --registry-username <THUNDER_ACR_USERNAME> \
  --registry-password <THUNDER_ACR_PASSWORD> \
  --cpu 4 \
  --memory 8 \
  --ports 3000 \
  --ip-address Private \
  --environment-variables \
    CONCURRENT=15 \
    TIMEOUT=1800000 \
    RELAY_NAMESPACE=<YOUR_RELAY_NAMESPACE> \
    RELAY_HYCO=<YOUR_RELAY_HYCO> \
    RELAY_LISTEN_KEY=<YOUR_RELAY_LISTEN_KEY> \
  --restart-policy Always

# Check status
az container show \
  --resource-group rg-thunder-browserless \
  --name thunder-browserless \
  --query "{status:instanceView.state, ip:ipAddress.ip}" \
  -o table

Option 3 : Azure Kubernetes Service (AKS)

Pour les organisations qui ont déjà un cluster AKS.

# Create namespace
kubectl create namespace thunder

# Create image pull secret
kubectl create secret docker-registry thunder-acr \
  --namespace thunder \
  --docker-server=<THUNDER_ACR_SERVER> \
  --docker-username=<THUNDER_ACR_USERNAME> \
  --docker-password=<THUNDER_ACR_PASSWORD>

# Create secrets for environment variables
kubectl create secret generic thunder-browserless-secrets \
  --namespace thunder \
  --from-literal=RELAY_LISTEN_KEY=<YOUR_RELAY_LISTEN_KEY>

Enregistrez le fichier suivant sous thunder-browserless.yaml :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: thunder-browserless
  namespace: thunder
spec:
  replicas: 1
  selector:
    matchLabels:
      app: thunder-browserless
  template:
    metadata:
      labels:
        app: thunder-browserless
    spec:
      imagePullSecrets:
        - name: thunder-acr
      containers:
        - name: thunder-browserless
          image: <THUNDER_ACR_SERVER>/thunder-browserless:latest
          ports:
            - containerPort: 3000
          env:
            - name: CONCURRENT
              value: "15"
            - name: TIMEOUT
              value: "1800000"
            - name: RELAY_NAMESPACE
              value: "<YOUR_RELAY_NAMESPACE>"
            - name: RELAY_HYCO
              value: "<YOUR_RELAY_HYCO>"
            - name: RELAY_LISTEN_KEY
              valueFrom:
                secretKeyRef:
                  name: thunder-browserless-secrets
                  key: RELAY_LISTEN_KEY
          resources:
            requests:
              cpu: "2"
              memory: "4Gi"
            limits:
              cpu: "4"
              memory: "8Gi"
          startupProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 10
            failureThreshold: 30
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 30
            timeoutSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 10
            timeoutSeconds: 10
            failureThreshold: 3
---
apiVersion: v1
kind: Service
metadata:
  name: thunder-browserless
  namespace: thunder
spec:
  type: ClusterIP
  selector:
    app: thunder-browserless
  ports:
    - port: 3000
      targetPort: 3000
      protocol: TCP

Appliquez-le :

kubectl apply -f thunder-browserless.yaml

Option 4 : Docker (VM ou on-prem)

Pour exécuter directement sur une VM ou un serveur on-prem.

# Login to Thunders's ACR
docker login <THUNDER_ACR_SERVER> \
  -u <THUNDER_ACR_USERNAME> \
  -p <THUNDER_ACR_PASSWORD>

# Pull the image
docker pull <THUNDER_ACR_SERVER>/thunder-browserless:latest

# Run the container
docker run -d \
  --name thunder-browserless \
  --restart unless-stopped \
  -p 3000:3000 \
  -e CONCURRENT=15 \
  -e TIMEOUT=1800000 \
  -e RELAY_NAMESPACE=<YOUR_RELAY_NAMESPACE> \
  -e RELAY_HYCO=<YOUR_RELAY_HYCO> \
  -e RELAY_LISTEN_KEY=<YOUR_RELAY_LISTEN_KEY> \
  --shm-size=2g \
  <THUNDER_ACR_SERVER>/thunder-browserless:latest

Important : Le flag --shm-size=2g est requis. Chromium utilise /dev/shm pour la mémoire partagée, et la valeur par défaut de 64MB est insuffisante pour l’automatisation navigateur.

Enregistrez sous docker-compose.yml :

services:
  thunder-browserless:
    image: <THUNDER_ACR_SERVER>/thunder-browserless:latest
    container_name: thunder-browserless
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - CONCURRENT=${CONCURRENT:-15}
      - TIMEOUT=${TIMEOUT:-1800000}
      - RELAY_NAMESPACE=${RELAY_NAMESPACE}
      - RELAY_HYCO=${RELAY_HYCO}
      - RELAY_LISTEN_KEY=${RELAY_LISTEN_KEY}
    shm_size: 2g
    deploy:
      resources:
        limits:
          cpus: "4.0"
          memory: 8G
        reservations:
          cpus: "2.0"
          memory: 4G

Créez un fichier .env à côté de docker-compose.yml :

RELAY_NAMESPACE=your-relay.servicebus.windows.net
RELAY_HYCO=your-hybrid-connection
RELAY_LISTEN_KEY=your-listen-key
CONCURRENT=15
TIMEOUT=1800000

Lancez :

docker compose up -d

Health checks et monitoring

Endpoint de santé

Le conteneur expose les endpoints suivants :

GET /health — Retourne l’état de santé avec un score
GET /healthz — Alias de /health

Réponse saine (HTTP 200) :

{
  "origin": "http://localhost:3000",
  "healthy": true,
  "score": 85,
  "error": null,
  "pressure": {
    "cpu": 15,
    "memory": 45,
    "running": 2,
    "maxConcurrent": 15,
    "queued": 0,
    "isAvailable": true
  },
  "scores": {
    "cpu": 84,
    "memory": 44,
    "concurrent": 87
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Réponse non saine (HTTP 503) :

Renvoyée lorsque le CPU dépasse 95%, la mémoire dépasse 80%, ou que les sessions simultanées sont au maximum.

Recommandations de monitoring

Interroger /health toutes les 15 à 30 secondes
Alerter quand healthy est false pendant plus de 2 checks consécutifs
Surveiller pressure.running vs pressure.maxConcurrent pour le capacity planning
Suivre les tendances scores.cpu et scores.memory pour les décisions de scaling

Voir les logs

Azure Container Apps :

az containerapp logs show -g  -n  --follow

Azure Container Instances :

az container logs --resource-group <resource-group> --name <container-name> --follow

Docker :

docker logs -f thunder-browserless

Kubernetes :

kubectl logs -f deployment/thunder-browserless -n thunder

Dépannage

Le conteneur ne démarre pas

->Vérifiez les logs pour identifier des variables manquantes :

Required environment variable RELAY_NAMESPACE is not set

Assurez-vous que toutes les variables requises sont définies.

->Vérifiez les identifiants ACR :

echo '<password>' | docker login <THUNDER_ACR_SERVER> -u <username> --password-stdin
docker pull <THUNDER_ACR_SERVER>/thunder-browserless:latest

Le pont Relay ne se connecte pas

Vérifiez la connectivité sortante sur le port 443 vers *.servicebus.windows.net
Vérifiez les logs du pont relay pour les erreurs de connexion
Vérifiez que RELAY_NAMESPACE, RELAY_HYCO et RELAY_LISTEN_KEY sont corrects
Le pont relay se reconnecte automatiquement toutes les 5 secondes en cas de déconnexion

Le health check renvoie 503

Seuil CPU dépassé : Réduisez CONCURRENT ou allouez plus de CPU
Seuil mémoire dépassé : Allouez plus de mémoire ou réduisez CONCURRENT
Toutes les sessions occupées : Attendez la fin des sessions ou augmentez CONCURRENT

Les sessions navigateur expirent

Augmentez TIMEOUT (par défaut : 1800000ms = 30 minutes)
Vérifiez la latence réseau entre votre infrastructure et Azure Relay

Erreurs de mémoire partagée

Si vous utilisez Docker, assurez-vous que --shm-size=2g est défini. Chromium nécessite plus que les 64MB par défaut.

Guide de dimensionnement des ressources

Sessions simultanées	CPU	Mémoire	Mémoire partagée
5	2 cœurs	4 GB	1 GB
15 (par défaut)	4 cœurs	8 GB	2 GB
30	8 cœurs	16 GB	4 GB
60	16 cœurs	32 GB	8 GB

Ces recommandations sont des minimums. Les besoins réels dépendent de la complexité des pages web testées.

Exigences réseau

Sens	Protocole	Port	Destination	Objectif
Sortant	HTTPS/WSS	443	`*.servicebus.windows.net`	Connexion Azure Relay
Sortant	HTTPS	443	Applications web cibles	Automatisation navigateur
Entrant (optionnel)	HTTP	3000	Réseau local	Health checks (non requis pour le relay)

Aucun accès internet entrant n’est requis pour que la connexion relay fonctionne.

Pour toute assistance technique ou question liée à l’architecture, veuillez contacter notre équipe support à l’adresse suivante : [email protected]

Autres lectures connexes susceptibles de vous être utiles :

→Tests de navigateur auto-hébergés via Azure Relay