Documentation

Présentation

Socle est un panel d’hébergement que vous installez sur votre propre serveur. Il configure les logiciels nécessaires (nginx, PHP, Node.js, MariaDB, PostgreSQL, MongoDB, Redis, DNS, FTP, pare-feu) puis vous laisse tout gérer depuis votre navigateur.

Deux types de comptes utilisent le panel :

• Les administrateurs gèrent le serveur, les clients, les formules et tous les abonnements.
• Les clients ne voient que leurs abonnements, dans les limites de leur formule.

Comment Socle protège le serveur

Le panel tourne sous un compte sans privilèges. Pour agir sur le système, il passe par un service séparé qui n’accepte qu’une liste fermée d’opérations, vérifie chaque paramètre, et lance les programmes sans jamais passer par un shell. Chaque abonnement a son propre compte système : ses sites, ses applications et ses fichiers lui appartiennent, et un client ne peut jamais atteindre plus que ce qu’il atteindrait en SFTP.

Installation

Prérequis

• Un serveur dédié ou un VPS sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04, de préférence installé à neuf.
• Un accès root (ou sudo).
• 2 Go de mémoire au minimum, 4 Go conseillés avec MongoDB ou plusieurs applications Node.js.
• Les ports 80 et 443 joignables depuis Internet, pour les sites et les certificats.

Lancer l’installation

Créez d’abord votre compte sur compte.soclepanel.com : votre clé de licence arrive par e-mail. Puis, sur le serveur :

curl -fsSL https://api.soclepanel.com/install.sh | sudo SOCLE_LICENSE=SOCLE-XXXX-XXXX-XXXX-XXXX bash

La commande télécharge Socle, vérifie son empreinte, installe et configure tout, active la licence, puis affiche l’adresse du panel et le mot de passe du premier administrateur. Ce mot de passe n’est affiché qu’une seule fois : notez-le.

Quelques variables permettent de régler l’installation :

Le pare-feu n’ouvre que l’essentiel : SSH, HTTP, HTTPS, le panel, le DNS et le FTP. Les bases de données n’écoutent que sur la machine, sauf si vous ouvrez les connexions distantes dans les réglages.

Premiers pas

1. Ouvrez l’adresse affichée à la fin de l’installation (https://votre-serveur:8443) et connectez-vous.
2. Activez la double authentification dans Mon compte : le panel vous le rappelle tant qu’elle n’est pas active.
3. Dans Réglages › Panel › Adresse du panel, donnez-lui un nom de domaine, par exemple panel.votre-domaine.fr : il obtient un certificat et s’ouvre sans le port 8443.
4. Dans Réglages › DNS, choisissez où vivent vos zones : le serveur DNS intégré, Cloudflare, ou ailleurs.
5. Créez votre premier abonnement depuis Abonnements › Nouvel abonnement.

Licence et offres

Une licence vaut pour un serveur. Toutes les offres ont toutes les fonctionnalités ; seul change le nombre de domaines hébergés :

Comptent les domaines qui ont un hébergement (statique, PHP, Node.js, proxy, redirection) ; les domaines sans hébergement, utiles pour le DNS seul, sont gratuits. Un nouveau compte a 14 jours de l’offre Pro.

Activer, changer de serveur

• La clé donnée à l’installation est activée automatiquement. Sur un serveur déjà installé : Réglages › Panel › Licence, collez la clé.
• Pour changer de serveur, libérez la licence (depuis ce même écran, ou depuis votre espace client), puis activez-la sur le nouveau.
• Votre espace client montre le serveur où chaque licence est active, sa version et son dernier contact.

Si l’offre ne suffit plus, ou s’arrête

Rien ne s’arrête jamais : les sites restent en ligne. Au-delà de la limite de l’offre, seul l’ajout de nouveaux domaines est refusé, avec un message qui l’explique. À la fin de l’essai ou d’un abonnement, la licence passe en offre Gratuite.

Le serveur vérifie sa licence une fois par jour auprès d’api.soclepanel.com. S’il ne peut pas la joindre, il continue normalement pendant 30 jours. Pour vérifier tout de suite, après un changement d’offre : Réglages › Licence › Vérifier.

Paiement et factures

Depuis votre espace client : choisir une offre (au mois ou à l’année), changer de moyen de paiement, résilier, télécharger les factures. Les paiements passent par Stripe.

Abonnements

Un abonnement regroupe les domaines d’un même client ou d’un même projet. Il a son compte système, son dossier (/srv/sites/<domaine principal>), ses accès SFTP et FTP, ses bases de données, ses sauvegardes et ses tâches planifiées.

Sa vue d’ensemble montre l’espace utilisé, la dernière sauvegarde, le résultat de la dernière analyse de sécurité et la liste de ses sites.

Un abonnement peut exister sans hébergement : ses domaines ne servent alors qu’au DNS ou à des redirections. Il obtient un hébergement dès qu’un de ses domaines passe en type Statique, PHP ou Node.js.

Domaines et types de site

Chaque domaine ou sous-domaine d’un abonnement a un type :

Le dossier servi se règle dans Type de site. Pour une application monopage (React Router, Vue Router…), cochez l’option du même nom : les adresses qui ne correspondent à aucun fichier affichent index.html. Socle la coche tout seul au déploiement quand il reconnaît un routeur de ce type.

Les variables d’environnement d’un domaine se saisissent dans Variables : elles sont transmises à l’application Node.js et aux compilations des déploiements.

États d’un domaine

• En ligne : le site fonctionne normalement.
• Maintenance : les visiteurs voient une page de maintenance avec votre message ; vous continuez à travailler sur le site.
• Désactivé : le site ne répond plus et son application est arrêtée. Le client peut le réactiver.
• Suspendu : décidé par un administrateur, avec un motif. Le client ne peut plus rien modifier sur ce domaine.

Un administrateur peut aussi suspendre un abonnement entier : ses sites affichent une page d’indisponibilité, ses accès SFTP, FTP et SSH sont bloqués, ses applications, son Redis et ses conteneurs sont arrêtés. Rien n’est supprimé, et tout revient à la réactivation.

HTTPS et adresses

HTTPS › Activer demande un certificat Let’s Encrypt pour le domaine et ses alias, puis le renouvelle automatiquement. Le domaine doit d’abord pointer vers le serveur. La redirection de HTTP vers HTTPS est activée par défaut.

Dans Alias et redirections, ajoutez d’autres noms au même site (par exemple www) et choisissez la forme principale : avec ou sans www.

La prévisualisation donne une adresse temporaire pour montrer un site avant que son domaine pointe vers le serveur, par exemple pendant une migration.

PHP

Chaque domaine PHP a son propre processus PHP-FPM, sous le compte de l’abonnement : un réglage ne touche que ce site. Dans Réglages PHP, choisissez la version et les valeurs courantes (mémoire, taille des envois, durée d’exécution…).

Les versions disponibles se gèrent dans Réglages › Serveur › Versions de PHP : seules les versions encore maintenues (8.1 et suivantes) sont proposées. Une version utilisée par un site ne peut pas être retirée.

Applications Node.js

Une application Node.js est lancée par PM2 sous le compte de l’abonnement et redémarrée si elle s’arrête. Socle lui donne un port local (variable PORT) et nginx lui transmet les requêtes du domaine.

• Dans Application, choisissez le fichier de démarrage ou un script du package.json (par exemple start).
• Commandes npm lance l’installation des dépendances ou un script, avec leur sortie à l’écran.
• Journal de l’application affiche ce que l’application écrit.

Les scripts qui ne s’arrêtent jamais (dev, watch…) sont refusés comme scripts de compilation : ils bloqueraient le déploiement.

WordPress

Sur un domaine PHP, l’onglet WordPress permet :

• d’installer WordPress, avec sa base de données, en un clic ;
• de se connecter à l’administration de WordPress sans mot de passe, par un lien à usage unique ;
• de mettre à jour WordPress, ses extensions et ses thèmes ;
• de changer le mot de passe d’un utilisateur ;
• de passer le site en maintenance ;
• d’activer le mode secours, qui désactive les extensions quand l’une d’elles casse le site.

Socle protège aussi chaque WordPress : PHP interdit dans le dossier des envois, XML-RPC coupé, éditeur de fichiers désactivé.

Fichiers, SFTP et SSH

Le gestionnaire de fichiers permet de parcourir, modifier, envoyer, télécharger, compresser et décompresser les fichiers d’un abonnement. Chaque action s’exécute sous le compte de l’abonnement.

Dans Accès, vous choisissez comment se connecter de l’extérieur :

• SFTP : enfermé dans le dossier de l’abonnement, par mot de passe ou par clé SSH ;
• FTPS : FTP avec chiffrement obligatoire ;
• Shell SSH : un terminal complet, seulement si un administrateur l’autorise pour cet abonnement.

Tâches planifiées

Une tâche planifiée lance, à l’heure voulue, une commande, un script PHP ou l’appel d’une adresse. Elle s’exécute sous le compte de l’abonnement, et le panel garde le résultat de sa dernière exécution.

Déploiement depuis GitHub

Connecter un dépôt

1. Dans l’onglet Déploiement du domaine, indiquez le dépôt (propriétaire/nom), la branche et le dossier où le placer.
2. Socle crée une clé de déploiement : ajoutez-la au dépôt sur GitHub (Settings › Deploy keys), en lecture seule.
3. Choisissez les étapes, puis lancez le premier déploiement.

Les étapes

1. Récupération du code et comparaison avec la version en ligne.
2. Dépendances : installées seulement si elles ont changé. Socle reconnaît npm, pnpm, yarn et bun à leur fichier de verrouillage.
3. Compilation : un script du package.json, par exemple build.
4. Mise en place de la nouvelle version.
5. Avant le démarrage : un script lancé avant le redémarrage, typiquement les migrations de la base (prisma migrate deploy).
6. Commandes libres, si l’abonnement a le droit au shell.
7. Redémarrage de l’application Node.js.
8. Contrôle : le site doit répondre sans erreur dans les 30 secondes.

Les dépendances et la compilation se font dans un dossier temporaire : tant qu’elles n’ont pas réussi, rien ne change en ligne. Un fichier modifié directement sur le serveur est détecté : Socle vous demande s’il faut le garder ou le remplacer, et garde une copie de ce qu’il remplace.

Monorepos

Pour un dépôt qui contient plusieurs applications (pnpm, yarn ou npm workspaces), indiquez le dossier de l’application, par exemple apps/web : les dépendances s’installent à la racine du dépôt, la compilation et le script avant le démarrage se lancent dans ce dossier.

Déploiement automatique

Activez Déploiement automatique et ajoutez le webhook affiché à votre dépôt sur GitHub : chaque push sur la branche lance un déploiement. Un webhook Discord peut vous prévenir des réussites et des échecs.

Chaque déploiement garde son journal : commits apportés, fichiers changés, sortie de chaque étape. Revenir à cette version remet en ligne un déploiement précédent.

Importer un projet

Depuis un abonnement, Importer un projet prépare tout un projet à partir de son dépôt GitHub : domaines, bases de données, Redis, variables et déploiements.

1. Indiquez le dépôt et sa branche, puis Continuer.
2. Si Socle ne peut pas encore lire le dépôt, il vous donne une clé et un lien direct vers la page d’ajout de clé du dépôt sur GitHub. Collez-la, puis lancez l’analyse. Une seule clé suffit : les domaines créés l’utiliseront aussi.
3. Socle propose un plan : les applications trouvées (Next.js, NestJS, Vite, Astro, Express…), leur type, leurs scripts, les services dont elles ont besoin et les variables de leur .env.example.
4. Choisissez le domaine de chaque application. DATABASE_URL, REDIS_URL et les variables du même genre sont remplies avec les connexions que Socle crée, les secrets sont générés. Il ne reste qu’à saisir les clés de vos services externes.
5. Importer : Socle crée tout, lance les déploiements et active le redéploiement à chaque push.

Pour que les migrations se lancent seules, le projet doit avoir un script qui les fait, par exemple "db:migrate": "prisma migrate deploy" dans son package.json.

Projets Docker Compose

L’onglet Conteneurs d’un abonnement gère les projets décrits par un fichier compose.yaml ou docker-compose.yml. L’administrateur ajoute le projet (le dossier qui contient le fichier) ; le client peut ensuite le démarrer, appliquer ses changements, mettre à jour les images, l’arrêter et lire ses journaux.

Ce que Socle refuse

Docker tourne avec les droits les plus élevés du serveur. Avant chaque démarrage, Socle vérifie donc le fichier et refuse :

• le mode privilégié et les capacités ajoutées ;
• le réseau, les processus ou les périphériques du serveur ;
• un dossier monté hors du projet, et le socket Docker ;
• un port ouvert ailleurs que sur la machine : écrivez "127.0.0.1:8080:80", pas "8080:80".

Pour publier un service sur Internet, créez un domaine de type Proxy vers son port. Les dossiers montés dans le projet font partie des sauvegardes de l’abonnement, pas les volumes nommés de Docker.

Bases de données

L’onglet Bases de données d’un abonnement gère trois moteurs :

• MariaDB (compatible MySQL), avec phpMyAdmin connecté en un clic ;
• PostgreSQL, avec l’adresse de connexion prête à coller dans DATABASE_URL ;
• MongoDB, avec un explorateur intégré pour parcourir et modifier les documents.

Utilisateurs

Un utilisateur a accès à une base, ou à toutes les bases de l’abonnement (y compris celles créées plus tard). Il peut être en lecture seule. Par défaut, il ne se connecte que depuis le serveur ; vous pouvez l’autoriser depuis certaines adresses IP, ou depuis n’importe où.

Avec PostgreSQL, ce qu’un utilisateur crée appartient à la base et non à lui : les migrations et les autres utilisateurs de la base partagent les mêmes tables.

Tester un mot de passe

Quand une application n’arrive pas à se connecter, Tester vérifie le mot de passe qu’elle utilise, sans rien modifier. Pour MongoDB, le panel affiche aussi les connexions refusées récemment et leur raison.

Export et import

Exporter télécharge la base : .sql.gz pour MariaDB et PostgreSQL, archive .archive.gz pour MongoDB. Importer accepte ces formats, et les fichiers .dump de PostgreSQL. L’import s’exécute avec un compte temporaire limité à cette base : un fichier ne peut toucher ni une autre base, ni le serveur.

Connexions distantes

Par défaut, les bases n’écoutent que sur le serveur. Réglages › Bases de données › Connexions distantes les ouvre au réseau, moteur par moteur ; seuls les utilisateurs autorisés depuis une adresse peuvent alors s’y connecter.

Redis

Chaque abonnement peut activer son propre Redis, depuis l’onglet Bases de données. Il tourne sous le compte de l’abonnement, sur un port de la machine, avec un mot de passe.

• Connexion donne l’adresse prête à coller dans REDIS_URL, à tout moment.
• La mémoire maximale se règle (256 Mo au plus pour un client). Une fois pleine, Redis refuse les écritures au lieu d’effacer des données : aucune tâche en file d’attente n’est perdue.
• Les données peuvent être enregistrées sur disque : elles survivent alors aux redémarrages et font partie des sauvegardes.
• Vider supprime toutes les clés ; Nouveau mot de passe change l’accès.

Sauvegardes

Sauvegarde du serveur

Chaque nuit, Socle sauvegarde tous les abonnements (fichiers et bases) ainsi que la configuration du serveur : comptes, mots de passe, tâches planifiées, utilisateurs des bases, certificats, zones DNS. L’heure et le nombre de copies conservées se règlent dans Réglages › Sauvegardes › Planification.

Stockage distant

Une copie peut partir vers un stockage distant (SFTP, S3, FTP ou WebDAV). Elle est chiffrée avant de quitter le serveur avec une phrase de votre choix : le stockage ne voit ni les noms, ni le contenu. Gardez cette phrase en lieu sûr : sans elle, la copie est illisible.

Restaurer

Depuis une sauvegarde du serveur, vous restaurez au choix :

• un abonnement entier, même supprimé entre-temps, avec ses comptes et ses mots de passe ;
• un domaine, une base de données, une zone DNS ;
• le contenu seul, ou aussi la configuration.

Les clients peuvent aussi faire et restaurer les sauvegardes de leurs abonnements, fichiers et bases séparément.

DNS

Dans Réglages › DNS, choisissez où vivent vos zones :

• Serveur DNS intégré : le serveur répond lui-même pour vos domaines, avec vos serveurs de noms (jusqu’à six) ;
• Cloudflare : les zones restent chez Cloudflare, et le panel les modifie avec un jeton d’API ;
• Aucun : vous gérez le DNS ailleurs.

À la création d’un domaine, Socle crée sa zone et ses enregistrements vers le serveur. L’onglet DNS permet d’ajouter les autres enregistrements : MX et SPF de votre fournisseur d’e-mails, clés DKIM, vérifications… Une zone peut avoir ses propres serveurs de noms, et un serveur DNS secondaire peut recopier vos zones pour la redondance.

Pour utiliser vos propres serveurs de noms, déclarez-les chez votre registrar avec leurs adresses IP (enregistrements de colle).

Clients et formules

Dans Clients, créez les comptes de vos clients et attribuez-leur des abonnements. Une formule fixe leurs limites : nombre d’abonnements, de domaines et de bases, taille des envois, accès au shell, applications Node.js, sauvegardes.

Dans Réglages › Panel › Marque, donnez au panel votre nom, votre logo, votre couleur et votre icône : vos clients voient votre marque, sur toutes les pages et sur l’écran de connexion.

Réglages › Sites › Noms de domaine interdits empêche un client d’ajouter certains domaines : ceux du panel et du serveur, une liste de grands services, et les vôtres.

Sécurité

Connexion au panel

• Double authentification par application (TOTP), conseillée pour tous et rappelée aux administrateurs.
• Réglages › Panel › Accès au panel : les adresses IP d’où les administrateurs peuvent se connecter, et la durée des sessions.
• Le Journal d’activité garde chaque action effectuée dans le panel.

Bannissements

Les adresses qui échouent trop souvent à se connecter (SSH, FTP, panel) sont bannies. Les seuils, la durée et la liste blanche se règlent dans Réglages › Sécurité, où vous pouvez aussi débannir une adresse.

Analyse des sites

Chaque nuit, Socle analyse les abonnements : fichiers suspects, PHP dans les dossiers d’envoi, fichiers du cœur de WordPress modifiés, processus et tâches planifiées inhabituels, extensions vulnérables. Les fichiers dangereux peuvent être mis en quarantaine, et les alertes envoyées par e-mail.

Réglages du serveur

Les réglages sont rangés par catégorie :

• Panel : identité, marque, adresse du panel, accès, mises à jour de Socle.
• Serveur : adresses du serveur, état des services, mises à jour du système, versions de PHP.
• Sites : prévisualisation, miniatures, noms de domaine interdits.
• Sécurité : adresses bannies, liste blanche, services surveillés, analyse des sites.
• Sauvegardes : sauvegardes du serveur, planification, stockage distant.
• Bases de données : noms des bases, connexions distantes.
• DNS : fournisseur, serveurs de noms, serveurs secondaires.
• E-mails : le serveur SMTP qui envoie les alertes.
• Outils : migration, diagnostic et réparation, journal d’activité.

État des services

Chaque logiciel du serveur avec son état, depuis quand il tourne et sa mémoire, et un bouton pour le démarrer ou le redémarrer. Les applications Node.js des sites y figurent aussi.

Diagnostic et réparation

Le diagnostic vérifie le serveur et les sites : services, espace disque, certificats, configuration. Réécrire la configuration de tous les sites remet chaque domaine en état.

Mises à jour du système

Les paquets à mettre à jour, les correctifs de sécurité, la mise à jour automatique des correctifs, et le redémarrage du serveur quand il est nécessaire.

Migration depuis Plesk

Réglages › Outils › Migration & transfert se connecte à votre serveur Plesk en SSH, liste ses abonnements, et les transfère : fichiers, bases de données avec leurs utilisateurs et mots de passe, comptes, DNS et clients.

1. Choisissez ce que vous transférez. Socle propose le bon type de site pour chaque domaine.
2. Les sites sont copiés ; ils restent en ligne sur Plesk pendant ce temps.
3. Vérifiez chaque site sur son adresse de prévisualisation.
4. Basculez : les domaines pointent vers Socle, et les certificats sont demandés.

Socle ne supprime jamais rien sur le serveur Plesk.

API

Chaque utilisateur peut créer des clés d’API dans Mon compte, en lecture seule ou complètes, avec une date d’expiration. Une clé agit avec les droits de son propriétaire.

curl -H "Authorization: Bearer socle_xxxxxxxx_…" https://panel.votre-domaine.fr/api/subscriptions

Les routes sont celles qu’utilise le panel lui-même ; les requêtes d’écriture prennent du JSON.

Mises à jour

Quand une nouvelle version de Socle est disponible, un bandeau apparaît pour les administrateurs : Mettre à jour l’installe en quelques minutes, sans toucher aux sites ni aux données. Les trois dernières versions restent sur le serveur, pour revenir en arrière si besoin.

Commandes du serveur

Pour les cas où le panel n’est pas joignable, quelques commandes, à lancer en root :