# Loxya | Documentation

## 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 !

> <i class="fas fa-info-circle"></i> **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&nbsp;! → [Voir les tarifs](/pricing)

> 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](/contact) pour en discuter&nbsp;!

<a href="/wiki/install#install-before" id="install-before" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### Avant de commencer

Pour pouvoir installer **Loxya v1.2**, il faut disposer&nbsp;:

- 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](/wiki/appendices#appendices-dependencies) 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.

> <i class="fas fa-info-circle"></i> **Note**&nbsp;: N'hésitez pas à faire un tour sur <a href="https://forum.robertmanager.org/t/tutoriels" target="_blank" rel="ugc nofollow noreferrer">la plateforme de support</a> à la recherche de tutoriels en vidéo, ou pour demander un peu d'aide à la communauté&nbsp;!


<a href="/wiki/install#install-copy" id="install-copy" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 1. Installer les fichiers source

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

- Celui de la **variante Open-source** est [<i class="fas fa-download"></i> téléchargeable sur cette page](/download).
- Celui de la **variante Premium** vous est fourni lors de [<i class="fas fa-crown"></i> l'achat d'une licence Premium](/pricing#pricing-licence).

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.

> <i class="fas fa-exclamation-triangle color-error"></i> **Important**  
> Le dossier dans lequel vous allez décompacter le code source sera le **dossier racine** de votre instance du logiciel.


<a href="/wiki/install#install-web-server" id="install-web-server" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 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&nbsp;:

- **Apache2**&nbsp;: le dossier racine du projet `/`.
- **Nginx**&nbsp;: 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&nbsp;: `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&nbsp;:

- `/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.


<a href="/wiki/install#install-db" id="install-db" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 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 😃 🌏 😘&nbsp;!

Attention, <i class="fas fa-edit"></i> **Notez bien** les informations de **connexion MySQL** suivantes, car vous en aurez besoin à [l'étape 4 de l'assistant d'installation](/wiki/wizard#wizard-step4)&nbsp;:

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


<a href="/wiki/install#install-premium-loader" id="install-premium-loader" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 4. Ajouter un module PHP <small>(<i class="fas fa-crown"></i> Premium uniquement)</small>


> <i class="fas fa-info-circle"></i> 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 «&nbsp;**loader**&nbsp;», 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.


<a href="/wiki/install#install-wizard" id="install-wizard" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 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](/wiki/wizard).

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


<a href="/wiki/install#install-after-install" id="install-after-install" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### 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 <small>(<i class="fas fa-crown"></i> Premium)</small>,
et pour le **nettoyage des données** de modèle obsolètes (comme les paniers de commande expirés <small>(<i class="fas fa-crown"></i>
Premium)</small>, 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**](/wiki/appendices#appendices-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**](/wiki/appendices#appendices-settings), notamment
en ce qui concerne l'**envoi des e-mails**, la [**politique de retour**](/wiki/usage#usage-return-policy), 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`&nbsp;:

```
# - 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`](/wiki/appendices#appendices-environment-variables).

#### **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](/wiki/appendices#appendices-logo-pdf).

#### **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](/wiki/appendices#appendices-bill-template).

<p style="max-width: 900px; text-align: center; font-size: 1.2rem; font-weight: 600">
    Maintenant, vous êtes prêt à utiliser Loxya&nbsp;!!!
</p>

<div class="flex flex--justify-center" style="max-width: 900px;">
    <i class="fas fa-rocket fa-3x color-lighter"></i>
    <i class="fas fa-rocket fa-3x color-light"></i>
    <i class="fas fa-rocket fa-3x color-medium"></i>
</div>


<a href="/wiki/install#install-problems" id="install-problems" class="wiki__page__link">
    <i class="fas fa-link"></i>
</a>

### Résolution des problèmes éventuels

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

> <i class="fas fa-info-circle"></i> **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 à <a href="https://calendly.com/loxya/support-installation" target="_blank" nofollow noreferrer>prendre rendez-vous <i class="fas fa-external-link-alt"></i></a> dès maintenant&nbsp;!

#### **Erreur 500 en visitant l'URL principale**

Plusieurs causes à ce problème sont possibles&nbsp;:

- 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 <a href="https://httpd.apache.org/docs/2.4/rewrite/remapping.html" target="_blank" rel="nofollow noreferrer">URL rewriting <i class="fas fa-external-link-alt"></i></a> 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&nbsp;:

- 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](https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_default_row_format) de la configuration globale de votre serveur MySQL n'est pas définie comme ceci&nbsp;:

- `innodb_default_row_format` = `DYNAMIC`

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

#### **Erreurs lors des migrations de la base de données**

**Erreur possible n°1&nbsp;:**

```
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&nbsp;!

**Erreur possible n°2&nbsp;:**

```
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](/contact) 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&nbsp;: `src/var/cache/routes.php`, et de réessayer.

> Si vous rencontrez d'autres problèmes, merci de nous en faire part sur <a href="https://forum.robertmanager.org" target="_blank">la plateforme de support</a>&nbsp;!