From 82e73e260bccbf709f5deabbc738508b7b74402d Mon Sep 17 00:00:00 2001 From: Allionix Date: Sun, 28 Jun 2026 15:49:45 +0200 Subject: [PATCH 1/2] feat(installation): document the one-command installation script (en + fr) --- docs/installation/installation.md | 2 + docs/installation/script.md | 120 +++++++++++++++++ .../current/installation/installation.md | 3 + .../current/installation/script.md | 122 ++++++++++++++++++ 4 files changed, 247 insertions(+) create mode 100644 docs/installation/script.md create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md diff --git a/docs/installation/installation.md b/docs/installation/installation.md index 052b190..76deb8a 100644 --- a/docs/installation/installation.md +++ b/docs/installation/installation.md @@ -24,6 +24,8 @@ The cloud offering is available for all Premium and Enterprise licenses. You can Self-hosted installation is more complex and requires validated accreditation. You will need a web server, a database, and PHP. You can follow the self-hosted installation instructions [here](./selfhosted). +For a fully automated setup, the [installation script](./script) installs and configures the entire stack on a fresh server in a single command. + :::warning Self-hosted installation requires system administration knowledge. If you are not confident, we recommend opting for Cloud installation. ::: diff --git a/docs/installation/script.md b/docs/installation/script.md new file mode 100644 index 0000000..ad1acf4 --- /dev/null +++ b/docs/installation/script.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 2 +translated: true +--- + +# Installation Script + +The **installation script** sets up a complete ClientXCMS stack on a fresh Linux +server with a single command. It installs PHP 8.3, MariaDB, Nginx, Redis and +Node.js, downloads ClientXCMS, configures everything and (optionally) obtains a +Let's Encrypt certificate - then hands over to the web installer for license +activation. + +It is the fastest way to self-host. If you prefer to install each component +manually, see [Self-hosted](./selfhosted); for multi-server deployments, see +[Ansible](./ansible). + +:::info Community script +This script is community-maintained and distributed separately from the +ClientXCMS core. Always review a script before running it as root. Source: +[github.com/alexwrite/clientxcms-installer](https://github.com/alexwrite/clientxcms-installer) +::: + +## Requirements + +- A **fresh server** with root access (or `sudo`). +- A valid **Community** (or higher) license - see [Requirements](./requis). +- One of the supported operating systems below. + +| Distribution | Versions | +|--------------|----------| +| Debian | 11, 12, 13 | +| Ubuntu | 22.04, 24.04 | +| Rocky Linux / AlmaLinux | 8, 9 | + +Architectures: `x86_64` and `arm64`. Minimum 2 GB RAM and 25 GB disk. + +:::warning +Run the script on a **dedicated** server. It installs and configures system-wide +services (Nginx, MariaDB, PHP-FPM, Redis); existing sites using these could be +affected. +::: + +## Quick start + +Run as root (or with `sudo`): + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/install.sh) +``` + +Choose **Install ClientXCMS**, then answer the prompts. The script prints a +summary and asks for confirmation before doing anything. + +## What it installs + +| Step | Detail | +|------|--------| +| Dependencies | PHP 8.3 + required extensions (Sury on Debian, ondrej PPA on Ubuntu, Remi on Rocky/Alma), MariaDB, Nginx, Redis, Node.js 20, Composer, Git | +| Application | `git clone` of ClientXCMS into `/var/www/clientxcms`, `composer install`, `npm run build` | +| Configuration | Writes `.env`, generates `APP_KEY`, wires the database and (optional) Redis drivers | +| Database | Creates the database and user, runs `php artisan migrate --force --seed` and `storage:link` | +| Services | Nginx vhost, scheduler cron, optional systemd queue worker | +| Security | Optional firewall rules and a Let's Encrypt certificate via certbot | + +## Interactive options + +During the run you will be asked for: + +- the **domain name** (FQDN) pointing to the server (or an IP for a local test); +- the default **locale** (`fr` / `en`); +- the **database** name, user and password (leave the password empty to generate a strong one); +- whether to use **Redis** for cache, sessions and queue; +- whether to install a persistent **queue worker** (systemd service); +- whether to open the **firewall** ports 22, 80 and 443; +- whether to obtain a **Let's Encrypt** certificate (the domain must already resolve to the server). + +:::info +If obtaining the Let's Encrypt certificate fails (DNS not propagated, ports +closed), the installation still completes - the site stays on HTTP and the +script shows the command to retry certbot later. +::: + +## After the script: finish in the browser + +Like every self-hosted installation, ClientXCMS is finalised through the **web +installer**, which activates your license online. Once the script completes: + +1. Open `http(s)://your-domain`. +2. Follow the wizard: settings → license → admin account. +3. Enter your **OAuth Client ID / Secret** from + [clientxcms.com/client/services](https://clientxcms.com/client/services/). + +## Unattended installation + +Every prompt has an environment-variable equivalent, so the installer module can +run non-interactively (CI, provisioning): + +```bash +env FQDN=panel.example.com APP_LOCALE=fr \ + MYSQL_DB=clientxcms MYSQL_USER=clientxcms \ + USE_REDIS=true CONFIGURE_WORKER=true \ + CONFIGURE_LETSENCRYPT=true email=admin@example.com \ + bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/clientxcms.sh) +``` + +Leave `MYSQL_PASSWORD` unset to auto-generate one. Other overridable variables +include `INSTALL_DIR`, `CLIENTXCMS_BRANCH`, `PHP_VERSION` and `NODE_VERSION`. + +## Uninstall + +Re-run the entrypoint and choose **Uninstall**, or run it directly: + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/uninstall.sh) +``` + +It removes the application, its services, vhost and cron, and asks before +dropping the database or deleting the files. A final opt-in step can also purge +the whole stack (PHP, MariaDB, Nginx, Redis, Node). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/installation/installation.md b/i18n/fr/docusaurus-plugin-content-docs/current/installation/installation.md index b374fbb..b43456b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/installation/installation.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/installation/installation.md @@ -15,6 +15,9 @@ Vous pouvez interchanger vos extensions à tout moment depuis votre espace clien L'offre cloud est disponible pour toutes les licences Premium et Entreprise. Vous pouvez retrouver plus d'information sur les offres cloud [ici](https://clientxcms.com/pricing). ## Autohébergement L'installation en autohébergement est plus complexe nécessitant une accreditation validée. Pour cela, vous devez disposer d'un serveur web, d'une base de données et de PHP. Vous pouvez suivre les instructions d'installation en autohébergement [ici](./selfhosted). + +Pour une mise en place entièrement automatisée, le [script d'installation](./script) installe et configure toute la stack sur un serveur vierge en une seule commande. + :::warning L'installation en autohébergement nécessite des connaissances en administration système. Si vous n'êtes pas sûr de vous, nous vous recommandons d'opter pour l'installation Cloud. ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md b/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md new file mode 100644 index 0000000..2d4469c --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md @@ -0,0 +1,122 @@ +--- +sidebar_position: 2 +--- + +# Script d'installation + +Le **script d'installation** met en place une stack ClientXCMS complète sur un +serveur Linux vierge en une seule commande. Il installe PHP 8.3, MariaDB, Nginx, +Redis et Node.js, télécharge ClientXCMS, configure le tout et (au choix) obtient +un certificat Let's Encrypt, puis passe la main à l'installateur web pour +l'activation de la licence. + +C'est la manière la plus rapide de s'autohéberger. Si vous préférez installer +chaque composant à la main, consultez l'[Autohébergement](./selfhosted) ; pour +un déploiement multi-serveurs, voir [Ansible](./ansible). + +:::info Script communautaire +Ce script est maintenu par la communauté et distribué séparément du cœur de +ClientXCMS. Relisez toujours un script avant de l'exécuter en root. Source : +[github.com/alexwrite/clientxcms-installer](https://github.com/alexwrite/clientxcms-installer) +::: + +## Prérequis + +- Un **serveur vierge** avec un accès root (ou `sudo`). +- Une licence **Community** (ou supérieure) valide - voir [Prérequis](./requis). +- L'un des systèmes d'exploitation supportés ci-dessous. + +| Distribution | Versions | +|--------------|----------| +| Debian | 11, 12, 13 | +| Ubuntu | 22.04, 24.04 | +| Rocky Linux / AlmaLinux | 8, 9 | + +Architectures : `x86_64` et `arm64`. Minimum 2 Go de RAM et 25 Go de disque. + +:::warning +Lancez le script sur un serveur **dédié**. Il installe et configure des services +au niveau système (Nginx, MariaDB, PHP-FPM, Redis) ; des sites existants qui les +utilisent pourraient être impactés. +::: + +## Démarrage rapide + +À lancer en root (ou avec `sudo`) : + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/install.sh) +``` + +Choisissez **Install ClientXCMS**, puis répondez aux questions. Le script affiche +un récapitulatif et demande confirmation avant toute action. + +## Ce qu'il installe + +| Étape | Détail | +|------|--------| +| Dépendances | PHP 8.3 + extensions requises (Sury sur Debian, PPA ondrej sur Ubuntu, Remi sur Rocky/Alma), MariaDB, Nginx, Redis, Node.js 20, Composer, Git | +| Application | `git clone` de ClientXCMS dans `/var/www/clientxcms`, `composer install`, `npm run build` | +| Configuration | Écrit le `.env`, génère l'`APP_KEY`, configure la base de données et (au choix) les drivers Redis | +| Base de données | Crée la base et l'utilisateur, exécute `php artisan migrate --force --seed` et `storage:link` | +| Services | Vhost Nginx, tâche planifiée (cron), worker de file systemd optionnel | +| Sécurité | Règles de pare-feu optionnelles et certificat Let's Encrypt via certbot | + +## Options interactives + +Pendant l'exécution, il vous sera demandé : + +- le **nom de domaine** (FQDN) pointant vers le serveur (ou une IP pour un test local) ; +- la **langue** par défaut (`fr` / `en`) ; +- le nom, l'utilisateur et le mot de passe de la **base de données** (laissez le mot de passe vide pour en générer un robuste) ; +- l'utilisation de **Redis** pour le cache, les sessions et la file ; +- l'installation d'un **worker** de file persistant (service systemd) ; +- l'ouverture des ports **pare-feu** 22, 80 et 443 ; +- l'obtention d'un certificat **Let's Encrypt** (le domaine doit déjà résoudre vers le serveur). + +:::info +Si l'obtention du certificat Let's Encrypt échoue (DNS non propagé, ports +fermés), l'installation se termine quand même - le site reste en HTTP et le +script affiche la commande pour relancer certbot plus tard. +::: + +## Après le script : finaliser dans le navigateur + +Comme toute installation en autohébergement, ClientXCMS se finalise via +l'**installateur web**, qui active votre licence en ligne. Une fois le script +terminé : + +1. Ouvrez `http(s)://votre-domaine`. +2. Suivez l'assistant : paramètres → licence → compte administrateur. +3. Renseignez votre **OAuth Client ID / Secret** depuis + [clientxcms.com/client/services](https://clientxcms.com/client/services/). + +## Installation non-interactive + +Chaque question a un équivalent en variable d'environnement, ce qui permet de +lancer le module d'installation sans interaction (CI, provisioning) : + +```bash +env FQDN=panel.example.com APP_LOCALE=fr \ + MYSQL_DB=clientxcms MYSQL_USER=clientxcms \ + USE_REDIS=true CONFIGURE_WORKER=true \ + CONFIGURE_LETSENCRYPT=true email=admin@example.com \ + bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/clientxcms.sh) +``` + +Laissez `MYSQL_PASSWORD` vide pour en générer un automatiquement. Parmi les +autres variables surchargeables : `INSTALL_DIR`, `CLIENTXCMS_BRANCH`, +`PHP_VERSION` et `NODE_VERSION`. + +## Désinstallation + +Relancez le point d'entrée et choisissez **Uninstall**, ou lancez-le directement : + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/uninstall.sh) +``` + +Il retire l'application, ses services, le vhost et le cron, et demande +confirmation avant de supprimer la base de données ou les fichiers. Une dernière +étape optionnelle peut aussi purger toute la stack (PHP, MariaDB, Nginx, Redis, +Node). From 035f996a1a9dacae932e1258001ca0f4286f170b Mon Sep 17 00:00:00 2001 From: Allionix Date: Sun, 28 Jun 2026 16:22:37 +0200 Subject: [PATCH 2/2] docs(installation): document the update command in the script page (en + fr) --- docs/installation/script.md | 14 ++++++++++++++ .../current/installation/script.md | 15 +++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/docs/installation/script.md b/docs/installation/script.md index ad1acf4..20643ac 100644 --- a/docs/installation/script.md +++ b/docs/installation/script.md @@ -107,6 +107,20 @@ env FQDN=panel.example.com APP_LOCALE=fr \ Leave `MYSQL_PASSWORD` unset to auto-generate one. Other overridable variables include `INSTALL_DIR`, `CLIENTXCMS_BRANCH`, `PHP_VERSION` and `NODE_VERSION`. +## Updating + +Update an existing install to the latest version. Re-run the entrypoint and +choose **Update**, or run it directly: + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/update.sh) +``` + +It follows the [Git upgrade procedure](./upgrade): maintenance mode, a database +backup (saved to `storage/backups/`), `git pull`, `composer install`, migrations +and extension updates, cache clear, asset rebuild, then it lifts maintenance and +runs the post-update hook. Set `SKIP_BACKUP=true` to skip the backup. + ## Uninstall Re-run the entrypoint and choose **Uninstall**, or run it directly: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md b/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md index 2d4469c..021ca62 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/installation/script.md @@ -108,6 +108,21 @@ Laissez `MYSQL_PASSWORD` vide pour en générer un automatiquement. Parmi les autres variables surchargeables : `INSTALL_DIR`, `CLIENTXCMS_BRANCH`, `PHP_VERSION` et `NODE_VERSION`. +## Mise à jour + +Mettez à jour une installation existante vers la dernière version. Relancez le +point d'entrée et choisissez **Update**, ou lancez-le directement : + +```bash +bash <(curl -sSL https://raw.githubusercontent.com/alexwrite/clientxcms-installer/main/installers/update.sh) +``` + +Il suit la [procédure de mise à jour Git](./upgrade) : mode maintenance, +sauvegarde de la base de données (dans `storage/backups/`), `git pull`, +`composer install`, migrations et mises à jour d'extensions, vidage des caches, +recompilation des assets, puis sortie du mode maintenance et exécution du hook +de post-mise à jour. Définissez `SKIP_BACKUP=true` pour ignorer la sauvegarde. + ## Désinstallation Relancez le point d'entrée et choisissez **Uninstall**, ou lancez-le directement :