Installation

Cette page s'adresse aux utilisateurs qui veulent se charger eux-mêmes de l'installation de Loxya sur leur propre serveur web. Si vous disposez d'un abonnement à l'une de nos offres hébergées, l'installation du logiciel est effectuée par nos soins !

Bon à savoir
Si vous n'avez pas le temps d'effectuer vous-même cette installation, nous pouvons vous fournir une instance privée du logiciel clé-en-main, hébergée par nos soins, en quelques clics ! → Voir les tarifs

Si vous tenez à l'installer sur votre propre serveur mais que vous n'avez pas le temps ou les compétences pour le faire, nous pouvons nous en charger. L'installation sur site est une prestation dont le montant dépend de la configuration existante de votre serveur. Merci de nous contacter pour en discuter !

Avant de commencer

Pour pouvoir installer Loxya v1.2, il faut disposer :

  • d'un serveur web Apache2 ou Nginx, sur lequel est installé PHP 8.1 ou 8.2 ou 8.3 (en 64 bits),
  • d'un serveur MySQL 5.7.9 (ou MariaDB 10.2.7) ou supérieur (voir les versions compatibles pour plus d'infos).

Assurez-vous d'avoir le droit d'accéder au serveur MySQL. Les informations de connexion à la base de données vous seront demandées lors de l'installation.

Aussi, veuillez vous assurer que le serveur web est paramétré sur le même fuseau horaire que vos utilisateurs, car c'est le serveur qui prend en charge l'horodatage des opérations effectuées dans Loxya.

Enfin, il est recommandé d'installer Loxya sur un serveur qui dispose d'au moins 512 Mo de mémoire vive (RAM), pour éviter les dépassements de mémoire.

Note : N'hésitez pas à faire un tour sur la plateforme de support à la recherche de tutoriels en vidéo, ou pour demander un peu d'aide à la communauté !

1. Installer les fichiers source

Avant tout, il faut disposer du fichier ZIP contenant la dernière version du logiciel.

Ensuite, il suffit de décompacter le contenu de l'archive dans un dossier de votre serveur, en notant bien le chemin absolu de ce dossier.

Important
Le dossier dans lequel vous allez décompacter le code source sera le dossier racine de votre instance du logiciel.

2. Configurer le serveur web

Maintenant, il faut créer un hôte virtuel (virtual host) pour votre serveur Apache ou Nginx. En utilisant le chemin absolu du dossier noté à l'étape précédente, ce virtual host devra pointer vers :

  • Apache2 : le dossier racine du projet /.
  • Nginx : le sous-dossier du projet /src/public.

Ensuite, il faut s'assurer de la présence sur le serveur de toutes les extensions (modules) PHP suivants : bcmath, curl, dom, fileinfo, gettext, iconv, intl, json, mbstring, pcre, PDO, pdo_mysql, openssl, et xml.

Enfin, il faut vérifier que l'utilisateur système du serveur (typiquement www-data pour un serveur Apache) a bien accès en écriture aux dossiers et sous-dossiers suivants :

  • /data,
  • /src/App/Config.
  • /src/var/cache,
  • /src/var/logs,
  • /src/var/tmp,

Sur un serveur Linux, vous pouvez utiliser la commande chown www-data:www-data -R [dossier] pour vous en assurer.

3. Créer une base de données

Utilisez votre moyen habituel pour créer la base de données (via l'espace client de votre hébergeur, via un phpMyAdmin, ou même avec une requête SQL directement). Lors de la création, veillez à bien choisir l'interclassement utf8mb4_unicode_ci, qui permettra à Loxya d'utiliser correctement tous les caractères, même les 😃 🌏 😘 !

Attention, Notez bien les informations de connexion MySQL suivantes, car vous en aurez besoin à l'étape 4 de l'assistant d'installation :

  • nom du serveur MySQL hôte,
  • nom de la base de données,
  • nom de l'utilisateur MySQL ayant accès à la base de données,
  • mot de passe d'accès pour cet utilisateur.

4. Ajouter un module PHP ( Premium uniquement)

Cette étape est spécifique à la variante Premium du logiciel.
Si vous installez la variante open-source, vous pouvez passer cette étape.

Il s'agit d'installer un module PHP spécial, le « loader », qui permettra d'exécuter correctement le logiciel.

Si vous visitez l'URL de votre instance du logiciel avec un navigateur internet, une page indiquant l'absence de ce loader s'affichera. Sur cette page, vous trouverez un lien qui vous permettra de télécharger le bon loader adapté à votre serveur (environnement, type, version...), ainsi que les instructions pour l'installer correctement.

Une fois que c'est installé, n'oubliez pas de redémarrer votre serveur web pour que le loader soit pris en compte, et vous pourrez ensuite passer à l'étape suivante.

5. Lancer l'assistant d'installation

Vous devriez maintenant avoir accès au logiciel. Si vous visitez l'adresse de votre Loxya dans un navigateur web (Firefox, Chrome, Opéra...), vous devriez voir apparaître la première page de l'assistant d'installation.

Quand vous aurez passé toutes les étapes de l'assistant, votre instance de Loxya sera opérationnelle !

6. Après l'installation

Quand votre instance de Loxya est installée, que vous avez accès à son interface et que tout fonctionne correctement, vous devez effectuer quelques réglages manuellement, afin que votre instance de Loxya corresponde parfaitement à votre utilisation.

Tâches CRON

Il est important de mettre en place des tâches CRON qui permettront à Loxya de fonctionner correctement, notamment pour l'envoi des notifications en cas de non-retour du matériel ( Premium), et pour le nettoyage des données de modèle obsolètes (comme les paniers de commande expirés ( Premium), par exemple).

Pour cela, il faut se référer au fichier src/App/Config/CRON.json, qui décrit les commandes à lancer avec leur récurrence. Voir l'annexe sur les tâches CRON pour plus d'informations sur le sujet.

Par exemple, la commande de nettoyage (cleanup) est à lancer une fois par heure, et les commandes d'envoi de notifications (comme notifications:reminders), une fois par jour.

Ajuster le fichier de configuration

Vous pouvez également effectuer réglages du fichier de configuration, notamment en ce qui concerne l'envoi des e-mails, la politique de retour, la désactivation de certaines fonctionnalités, et définir une palette de couleurs à proposer dans les champs de couleur de l'interface.

Créer un fichier .env

Aussi, vous pouvez spécifier la timezone de votre Loxya dans un fichier .env situé à la racine du projet, utile surtout si votre serveur n'est pas sur le même fuseau horaire que vos utilisateurs. Voici un exemple de contenu de fichier .env :

# - Permet de définir la timezone de l'application.
TIMEZONE=Europe/Paris

Pour plus d'informations sur ce fichier, voir l'annexe sur le fichier env.

Logo de votre entreprise

Vous pouvez copier un fichier image (jpg ou png) dans le dossier src/App/public/img, qui pourra servir de logo en en-tête des documents générés par Loxya (fiches de sortie, devis, factures...).

Une fois que le fichier de votre logo est présence dans ce dossier, il faut également ajouter son nom dans le paramètre companyData.logo du fichier de configuration. Plus de détails dans l'annexe sur le logo.

Adapter les modèles de documents générés par Loxya

Enfin, vous pouvez appliquer des modifications dans la présentation les fiches de sorties, les devis et les factures générés par Loxya. Pour cela, référez-vous aux annexes concernant la personnalisation.

Maintenant, vous êtes prêt à utiliser Loxya !!!

Résolution des problèmes éventuels

Voici les problèmes communs (et leurs solutions), que certains d'entre vous rencontreront peut-être.

Bon à savoir
Vous pouvez bénéficier d'une aide personnalisée de la part d'un développeur du logiciel, au téléphone ou en visio-conférence. Il pourra vous guider pour résoudre tout problème d'installation ou de paramétrage sur votre serveur.
Cette prestation est facturée 70,00 € H.T. de l'heure. N'hésitez pas à prendre rendez-vous dès maintenant !

Erreur 500 en visitant l'URL principale

Plusieurs causes à ce problème sont possibles :

  • Loxya ne fonctionne que si l'URL principale pointe directement à la racine du projet. Il n'est pas (encore) possible de l'installer dans un sous-dossier du domaine. Nous vous conseillons d'utiliser un sous-domaine (un virtual host, par ex. robert.votre-adresse.com) qui pointe directement sur le dossier racine du logiciel / pour un serveur Apache, ou dans le dossier /src/public pour un serveur Nginx.
  • Si vous utilisez un serveur Apache, il se peut que son URL rewriting soit mal configuré. Vérifiez en particulier que la directive RewriteBase est bien adaptée.
  • Il se peut aussi que les dossiers /data, /src/var/cache, /src/var/logs, /src/var/tmp, /src/install et /src/App/Config ne soient pas accessibles en écriture par l'utilisateur système du serveur (généralement sur Linux et Apache, cet utilisateur s'appelle www-data). Il faut impérativement les rendre accessibles en écriture pour cet utilisateur.

Erreur SQL à l'étape 5 de l'installation (migration de la base de données)

Ceci peut se produire quand la version de votre serveur SQL (MySQL ou MariaDB) ne prend pas en charge le type de colonne JSON. Pour corriger cela, il faut utiliser une version du serveur qui prend en charge ce type de données. Assurez-vous d'utiliser :

  • soit MySQL 5.7.9 (ou supérieur)
  • soit MariaDB 10.2.7 (ou supérieur)

Aussi, cette erreur peut se produire si la variable suivante de la configuration globale de votre serveur MySQL n'est pas définie comme ceci :

  • innodb_default_row_format = DYNAMIC

Pour trouver la valeur de cette variable, vous pouvez utiliser la requête MySQL suivante :
SHOW GLOBAL VARIABLES LIKE 'innodb_default%';.
Si sa valeur n'est pas DYNAMIC, alors il faut la modifier avec la commande MySQL :
SET GLOBAL innodb_default_row_format=DYNAMIC;.

Erreurs lors des migrations de la base de données

Erreur possible n°1 :

Phinx\Migration\AbstractMigration::__construct() : Argument #2 ($version) must be of type int, string given, called in /volume1/web/vendors/robmorgan/phinx/src/Phinx/Migration/Manager.php on line 824

Il se peut que votre système soit en 32 bits. Pour fonctionner, les migrations de Loxya (utilisant la lib Phinx de CakePHP) doivent être exécutées avec PHP 64 bits. Il faut donc mettre à jour votre système avec une version 64 bits !

Erreur possible n°2 :

The `event_materials` table contains some duplicate (event_id / material_id) that are not fixable automatically. Please see the app logs for details.

Cette erreur est dûe au fait qu'une opération de dé-doublonnage des données dans la table event_materials n'a pas pu être effectuée automatiquement. Il faut consulter le fichier de log src/var/logs/error-[date].log pour savoir quelle(s) ligne(s) pose(nt) problème dans la table, afin de les supprimer manuellement, puis relancer la migration.

Pour toute autre erreur de migration, il doit certainement s'agir d'un problème d'intégrité de vos données existantes, qu'il faudrait vérifier au cas par cas. Prenez rendez-vous dès maintenant avec l'un des membres de notre équipe, qui se fera un plaisir de vous aider à trouver l'origine du problème.

Erreur "Désolé, mais l'API est inaccessible... Erreur 0 : network error"

Cette erreur est typique d'une mauvaise configuration. Il faut vérifier que l'adresse que vous utilisez est bien exactement la même que celle qui est définie dans la configuration du serveur (fichier src/App/Config/settings.json), pour le paramètre apiUrl. Vérifiez tout spécialement la présence ou non du s dans https://..., ainsi que la valeur du paramètre useSSL qui doit correspondre (true si vous utilisez SSL, false sinon).

Erreur "The required resource was not found" sur l'URL principale

Il s'agit sans doute du fichier de cache du routing qui est obsolète.
Pour régler le souci, il suffit donc de supprimer le fichier : src/var/cache/routes.php, et de réessayer.

Si vous rencontrez d'autres problèmes, merci de nous en faire part sur la plateforme de support !