Configurer le serveur
La configuration se trouve dans le fichier .env, à la racine de l'application. Il contient des secrets : limitez ses droits au compte qui exécute le serveur, et ne l'envoyez jamais par e-mail une fois rempli.
Démarche
- Copiez le modèle
.env.examplesous le nom.env. - Renseignez toutes les valeurs marquées [OBLIGATOIRE]. Les valeurs [FACULTATIF] peuvent rester vides : la valeur par défaut s'applique.
- Déclarez chaque système cible (voir ci-dessous).
- Redémarrez le serveur et lisez ses logs : une valeur manquante ou invalide y est signalée, et le serveur refuse de démarrer si elle est indispensable.
La liste complète des variables est dans Variables du .env.
Paramètres du serveur
| Variable | Valeur |
|---|---|
NODE_ENV | production sur un serveur réel. |
SERVER_PROTOCOL | https si le serveur gère son certificat, http derrière un proxy (voir Derrière un proxy HTTPS). |
SERVER_PORT | Port d'écoute (4999 par défaut). |
TLS_KEY_FILE, TLS_CERT_FILE | En mode https : clé privée et certificat (suivi des certificats intermédiaires), au format PEM. |
LOG_LEVEL | info recommandé : connexions, envois et démarrage sont tracés. |
Clés et adresse de retour
| Variable | Valeur |
|---|---|
OAUTH_CALLBACK_URI | Adresse publique du serveur suivie de /auth/callback, par exemple https://save2erp.mon-entreprise.ch/auth/callback. Elle doit être déclarée à l'identique dans le client OAuth2 du système cible. |
OAUTH_COOKIE_CRYPTO_KEY | Clé de chiffrement des jetons : 32 octets encodés en base64. |
OAUTH_COOKIE_SIGN_KEY | Clé de signature des cookies : une autre valeur aléatoire. La changer déconnecte tous les utilisateurs. |
Pour générer chaque clé, sur un poste où Node.js est installé :
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"Déclarer un système cible
Seuls les systèmes déclarés dans le .env sont autorisés : un document lié à un autre système est refusé avec « Système inconnu ». Pour interdire un système, supprimez son bloc.
Le préfixe des variables indique le type du système. Aujourd'hui, le seul type disponible est SAP : ses variables commencent par SAP_, suivi du nom du système tel qu'il figure dans la propriété S2E_SystemKey des documents (voir Préparer les documents Word).
SAP_P01CLNT100_ENV=PROD # SBX, DEV, QUAL ou PROD : couleur du panneau
SAP_P01CLNT100_SID=P01
SAP_P01CLNT100_MANDT=100
SAP_P01CLNT100_APIBASE=https://sap.mon-entreprise.ch:44300/rest
SAP_P01CLNT100_OAUTH_SERVER=https://sap.mon-entreprise.ch:44300
SAP_P01CLNT100_OAUTH_CLIENT_ID=...
SAP_P01CLNT100_OAUTH_CLIENT_SECRET=...Le scope OAuth2 est commun à tous les systèmes (SAP_OAUTH_SCOPE), sauf si un système a le sien (SAP_P01CLNT100_OAUTH_SCOPE). Les informations à demander à l'équipe SAP sont détaillées dans Système cible : SAP.
Au démarrage, les logs indiquent pour chaque système son environnement, ou la raison pour laquelle il est refusé : variable manquante, environnement inconnu, chemin invalide…
Chemins des services REST
Le serveur appelle trois services, dont les chemins s'ajoutent à APIBASE : l'envoi (/attachments par défaut), la vérification avant l'envoi (/attachments/check) et le test de connexion (/attachments/healthcheck). Pour le mode concepteur, il appelle aussi, si le système cible les fournit, les droits de l'utilisateur (/attachments/permissions, variable SAP_PERMISSIONS_PATH) et les modèles (/attachments/readTemplateXml, variable SAP_TEMPLATE_PATH). Si votre système cible utilise d'autres chemins :
# Tous les systèmes de l'installation
SAP_ATTACHMENTS_PATH=/v1/document/attachments
SAP_CHECK_PATH=/v1/document/check
SAP_HEALTHCHECK_PATH=/v1/document/healthcheck
# Exception pour un système
SAP_Q01CLNT100_HEALTHCHECK_PATH=/attachment/healthcheck/version/1/Un chemin commence par / et ne contient ni //, ni ?, ni #, ni espace. Un chemin invalide rend le système inutilisable.
Couleur et icône du panneau
La couleur du panneau dépend de l'environnement du système (_ENV) :
| Environnement | Couleur des boutons |
|---|---|
| SBX | violet |
| DEV | ocre |
| QUAL | vert |
| PROD | bleu nuit |
Vous pouvez choisir une autre couleur pour un système, au format #RRGGBB, entre guillemets (un # non protégé commence un commentaire) :
SAP_P01CLNT100_COLOR="#0f6a99"Le fond de la page et la couleur de survol en sont déduits. Choisissez une couleur assez foncée pour que le texte blanc des boutons reste lisible (contraste d'au moins 4,5:1 avec le blanc), et évitez le rouge, réservé aux erreurs.
L'icône en haut du panneau peut aussi être remplacée, pour tous les systèmes (SAP_ICON) ou pour un seul (SAP_P01CLNT100_ICON) : fichier .svg ou .png, chemin absolu ou relatif au dossier de l'application. Un fichier absent ou d'un autre format rend le système inutilisable.
Appliquer une modification
Le .env est lu au démarrage : redémarrez le serveur après chaque modification (avec Docker : docker compose restart), puis vérifiez les logs.