Aller au contenu

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 ​

  1. Copiez le modèle .env.example sous le nom .env.
  2. Renseignez toutes les valeurs marquées [OBLIGATOIRE]. Les valeurs [FACULTATIF] peuvent rester vides : la valeur par défaut s'applique.
  3. Déclarez chaque système cible (voir ci-dessous).
  4. 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 ​

VariableValeur
NODE_ENVproduction sur un serveur réel.
SERVER_PROTOCOLhttps si le serveur gère son certificat, http derrière un proxy (voir Derrière un proxy HTTPS).
SERVER_PORTPort d'écoute (4999 par défaut).
TLS_KEY_FILE, TLS_CERT_FILEEn mode https : clé privée et certificat (suivi des certificats intermédiaires), au format PEM.
LOG_LEVELinfo recommandé : connexions, envois et démarrage sont tracés.

Clés et adresse de retour ​

VariableValeur
OAUTH_CALLBACK_URIAdresse 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_KEYClé de chiffrement des jetons : 32 octets encodés en base64.
OAUTH_COOKIE_SIGN_KEYClé 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é :

bash
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).

ini
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 :

ini
# 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) :

EnvironnementCouleur des boutons
SBXviolet
DEVocre
QUALvert
PRODbleu nuit

Vous pouvez choisir une autre couleur pour un système, au format #RRGGBB, entre guillemets (un # non protégé commence un commentaire) :

ini
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.