Installation

OAR est un relais que vous faites tourner sur votre propre machine. L’installer place la commande oar sur cette machine. Sous macOS et Linux, une seule ligne fait tout le travail : elle trouve ou télécharge Node.js, installe OAR, écrit la config et démarre le relais. Sous Windows, l’installateur a besoin que Node.js soit déjà là, et vous pouvez toujours installer avec npm ou depuis un checkout git.

Prérequis #

Rien d’autre n’est nécessaire pour installer. Vous ajoutez les fournisseurs une fois OAR lancé.

macOS et Linux #

curl -fsSL oar.sh/install | sh

Vous pouvez d’abord lire le script sur oar.sh/install. Il a besoin de curl ou wget, et de tar quand il doit télécharger Node.js. Il refuse de tourner en root : OAR s’installe par utilisateur, et rien n’a besoin de root.

Ce qu’il fait #

1. Il regarde ce que la machine possède et affiche un plan : quel Node.js il utilise, où il installe OAR, ce qu’il écrit dans votre profil shell et comment le relais sera démarré.
2. Il demande Continue? [Y/n]. Enter ou y poursuit ; toute autre réponse ne change rien.
3. Il installe le paquet @oar-sh/oar (la dernière version, sauf si vous fixez une version ou un canal).
4. Il lance oar setup --defaults --start : il écrit la config (un nouveau token d’auth, un accès pour cette machine uniquement, le premier port libre à partir de 3333, ou le port que vous fixez avec OAR_PORT) et démarre le relais. Il affiche l’URL du relais et un QR code.
5. Il affiche la version, vous indique que le relais tourne et liste les commandes oar, oar setup et oar doctor.

Sous Linux avec une session utilisateur systemd, le relais est démarré comme service utilisateur systemd, il revient donc après un redémarrage. Ailleurs (macOS, conteneurs, WSL sans systemd), il est démarré en arrière-plan, et oar start le relance après un redémarrage de la machine.

Où il installe #

Lequel des trois cas s’applique dépend du Node.js présent sur la machine.

Seul OAR utilise son propre Node.js. La commande oar de ~/.local/bin place ce Node.js en dernier dans PATH, de sorte qu’un Node.js à vous passe toujours en premier dans les sessions du relais.

Dans les deux derniers cas, quand ~/.local/bin n’est pas dans votre PATH, l’installateur liste le changement dans son plan, puis ajoute une ligne de commentaire (# added by the OAR installer) et une ligne export PATH au fichier de démarrage de votre shell : ~/.zshrc pour zsh, ~/.bash_profile pour bash sous macOS, ~/.bashrc pour bash sous Linux, ~/.profile sinon. Les nouveaux terminaux trouvent oar ; dans le terminal actuel, lancez la ligne export PATH=... que l’installateur affiche.

Options #

Les flags se placent après sh -s --. Les variables se placent avant sh.

Tout autre flag arrête l’installateur avec unknown option.

curl -fsSL oar.sh/install | sh -s -- --yes
curl -fsSL oar.sh/install | OAR_VERSION=0.9.19 OAR_PORT=3400 sh
curl -fsSL oar.sh/install | OAR_DRY_RUN=1 sh

Le relancer #

L’installateur peut être relancé à tout moment. Il réinstalle le paquet (la dernière version, sauf si vous en fixez une), il sert donc aussi de mise à jour. Il conserve une config existante, réutilise le Node.js propre à OAR s’il est encore assez récent, réécrit le lanceur oar et n’ajoute les lignes PATH à votre profil qu’une seule fois.

Le lancer sans terminal #

Passé par un pipe depuis curl, le script pose sa question sur le terminal. Sans terminal, par exemple dans un job de CI, il s’arrête avec no terminal to ask on et ne change rien. Passez --yes dans ce cas.

Là où il s’arrête #

• Il n’a pas de build Node.js pour les systèmes musl comme Alpine, ni pour d’autres processeurs que x64 et arm64. Installez vous-même Node.js 22.13 ou plus récent, puis relancez l’installateur.
• Si nodejs.org est injoignable, si un téléchargement ou une somme de contrôle échoue, ou si le Node.js téléchargé ne se lance pas, il s’arrête et n’installe rien.
• Les versions antérieures à 0.9.8 s’installent de la même façon, mais leur oar setup ne peut pas démarrer le relais. L’installateur se contente alors d’écrire la config et ne démarre pas le relais.

Windows #

irm oar.sh/install.ps1 | iex

Il faut PowerShell 5 ou plus récent, et Node.js 22.13 ou plus récent déjà installé. Contrairement à l’installateur macOS et Linux, il ne télécharge pas Node.js, ne demande pas de confirmation et ne démarre pas le relais. Il fait ceci :

1. Vérifie que node et npm existent et que Node.js est assez récent.
2. Affiche le plan.
3. Lance npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar.
4. Lance oar setup. Dans un terminal, il demande s’il faut créer un nouveau token d’auth, l’accès (cette machine uniquement, ou LAN), le port et, Ajouté en 0.9.15 comment le relais démarre : à l’ouverture de session, au démarrage avant que quiconque ne se connecte (une invite administrateur), ou pas du tout. Il écrit ensuite la config et affiche l’URL du relais.

Lancez ensuite oar start pour démarrer le relais ; le démarrage automatique choisi le démarre à la prochaine ouverture de session ou au prochain démarrage. oar autostart change le mode plus tard. La suite se trouve dans Premier lancement.

Définissez la variable dans la même fenêtre PowerShell avant la commande. L’installateur Windows n’a pas de OAR_PORT ; oar setup demande le port, ou vous lancez oar setup --port <port>.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Si l’installation réussit mais que oar est introuvable, ouvrez un nouveau terminal, puis lancez oar.cmd setup.

npm #

npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar
oar setup

npm 12 ne lance aucun script d’installation qu’on ne lui a pas dit d’autoriser. Deux des dépendances d’OAR (better-sqlite3, koffi) téléchargent leur binaire natif dans l’un de ces scripts : sans eux, l’installation réussit sous npm 12 et le relais échoue ensuite au démarrage. Ajouté en 0.9.14 Celui d’OAR (@oar-sh/oar) copie les données qu’une version antérieure gardait dans le paquet avant que npm ne les supprime ; voir Notes de mise à niveau pour 0.9.14. npm 10 et 11 acceptent le flag et n’en ont pas besoin. Les installateurs, oar update et le bouton Update (Mettre à jour) le passent d’eux-mêmes.

oar setup crée la config et affiche l’URL du relais, mais ne démarre pas le relais sauf si vous passez --start. Utilisez ensuite oar start. Le dossier global de npm doit être accessible en écriture et son dossier bin doit être dans votre PATH ; npm prefix -g indique où il se trouve. S’il exige root, n’utilisez pas sudo : lancez plutôt l’installateur sous macOS ou Linux. Pour mettre à jour plus tard, lancez oar update.

Depuis un checkout git #

git clone https://github.com/oar-sh/oar
cd oar
npm install
node bin/oar.js setup   # writes server/config.json with a fresh auth token
npm start               # the same as: node server/server.js

Un checkout diffère d’une installation globale sur trois points :

• L’état vit dans le dépôt : server/config.json, server/data/, server/uploads/ et server/logs/. Une installation globale garde son état dans ~/.oar (voir Où OAR garde ses fichiers et Fichiers et dossiers).
• Il ne se met jamais à jour tout seul. Mettez à jour avec git pull, npm install, puis redémarrez le relais avec 🌄 Restart web relay (Redémarrer le relais web) dans le menu ⋯ d’une conversation. oar update est destiné aux installations globales.
• oar start, oar stop et oar restart sont réservés aux installations globales. Dans un checkout, npm start fait tourner le relais au premier plan.

node server/server.js --port <port> --token <token> remplace la config le temps d’un lancement, sans l’enregistrer.

Par plateforme #

Après un redémarrage, oar start démarre un relais qui tourne en arrière-plan.

WSL #

Lancez l’installateur Linux dans la distribution, pas sous Windows. Avec le réseau par défaut de WSL, un port peut être libre dans la distribution alors qu’un programme Windows écoute dessus, et localhost:<port> dans un navigateur Windows atteint alors ce programme. Une nouvelle config prend donc le premier port libre des deux côtés, et oar setup refuse un port que Windows occupe. oar status, oar start et oar doctor avertissent quand Windows occupe le port du relais. Pour corriger, choisissez un autre port :

oar setup --port 3400

Une adresse LAN dans WSL est interne à WSL. Pour l’accès depuis un téléphone, utilisez un tunnel ou le réseau en miroir de WSL.

Désinstaller OAR #

Ajouté en 0.9.15 oar uninstall retire OAR de la machine et conserve vos données :

oar uninstall

Il arrête le relais (en attendant les turns en cours), supprime les entrées de démarrage automatique générées par OAR (l’unité systemd, ou l’entrée d’ouverture de session Windows et la tâche de démarrage, avec une invite administrateur pour la tâche de démarrage) et le wrapper d’extension Copilot écrit par OAR, puis fait supprimer le paquet par npm une fois la commande terminée. Les entrées que vous avez créées ou modifiées à la main restent et sont nommées. Votre config, votre base de données, vos fichiers envoyés et vos journaux restent dans le dossier d’état, et la commande indique où ; une installation ultérieure les reprend. oar uninstall donne les détails et chaque message.

Pour supprimer aussi les données :

oar uninstall --purge

Il supprime le dossier d’état après que vous avez tapé delete, et demande séparément avant de supprimer un dossier de données situé en dehors, un dossier dans un checkout git, ou rescued-package-data. Il refuse une racine de lecteur, votre dossier personnel, un dossier système et tout dossier qui ne contient ni la config ni la base de données d’OAR. Cela supprime vos conversations.

oar uninstall n’annule pas ce que l’installateur macOS et Linux a ajouté hors du paquet :

• le script oar dans ~/.local/bin, quand l’installateur l’y a placé (ses deuxième et troisième cas) ;
• les deux lignes qu’il a ajoutées au fichier de démarrage de votre shell, le cas échéant (le commentaire # added by the OAR installer et la ligne export PATH en dessous) ;
• ~/.oar/runtime, le Node.js propre à OAR, s’il est là. Il se trouve dans le dossier d’état, il reste donc sans --purge.

Avant 0.9.15, ou quand oar ne se lance plus, retirez les éléments à la main : arrêtez le relais avec oar stop et lancez oar service remove là où un service ou un démarrage automatique Windows est en place ; supprimez le paquet avec npm uninstall -g @oar-sh/oar, ou, après les deux autres cas de l’installateur, supprimez ~/.oar/npm ; puis les éléments ci-dessus, et ~/.oar ou %APPDATA%\oar seulement si vous voulez effacer vos données.

Où OAR garde ses fichiers #

Une installation globale garde son état dans ~/.oar (%APPDATA%\oar sous Windows ; OAR_STATE_ROOT le déplace) :

• config.json
• data/, avec la base de données et les fichiers envoyés
• logs/, avec server.log et server-err.log quand oar a démarré le relais, et un worker-<session>.log pour chaque worker de session Node

Mettre à jour le paquet avec npm n’y touche jamais. L’installateur macOS et Linux peut y ajouter deux dossiers qui ne sont pas de l’état : npm/ (le paquet, quand le dossier global de npm n’était pas accessible en écriture) et runtime/node/ (le Node.js propre à OAR). oar doctor affiche les chemins utilisés.

Ce que vous avez ensuite #

• La commande oar. Dans un terminal, oar seul ouvre un menu avec l’état du relais et les autres commandes. oar setup modifie les réglages (accès pour d’autres appareils, port, token), et oar url réaffiche l’URL du relais.
• Une config avec un nouveau token d’auth. Avec l’accès par défaut, le relais n’est joignable que depuis cette machine, à http://localhost:3333/ ou au port libre suivant.
• Sous macOS et Linux : un relais en cours d’exécution. Sous Windows et après une installation npm manuelle : un relais que vous démarrez avec oar start.

Vérifiez ce qui est installé :

oar --version
oar doctor

oar doctor affiche la version, Node.js, le mode d’installation, le dossier d’état, le chemin de la config, le port, si un token est défini, le chemin et la taille de la base de données, et quelles CLI de fournisseur répondent. Il ne change rien.

Dépannage #

Pour les problèmes après l’installation, voir Dépannage.