vps-docs/CLAUDE.md

Instructions pour Claude Code

Ce dépôt contient le guide d'installation VPS avec HestiaCP et la documentation de l'ancien serveur ISPConfig. Claude Code est utilisé pour assister l'utilisateur étape par étape dans la configuration du serveur.

Utilisateur

• Langue : français. Les fichiers techniques (code, configs) restent en anglais.
• Approche : avancer commande par commande, pas tout d'un coup. Expliquer chaque étape avant de l'exécuter.
• Éditeur : micro (/usr/bin/micro). Ne jamais demander d'ouvrir nano, vim ou un autre éditeur.
• Username serveur : scriptshadow

Modifications système avec sudo

Règle obligatoire quand une commande sudo est refusée ou pour toute modification de fichier système :

1. Écrire un script Python autonome dans ~/setup_xxx.py contenant toutes les modifications.
2. Proposer la commande combinée : sudo python3 ~/setup_xxx.py && rm ~/setup_xxx.py

Le script doit être autonome : imports, chemins absolus, vérifications. La suppression se fait dans la même commande.

Exception : si sudo -n fonctionne dans la session (NOPASSWD configuré), on peut exécuter directement.

Ne jamais demander à l'utilisateur d'ouvrir un éditeur pour modifier un fichier système.

Guide HestiaCP

Le guide complet est dans hestiacp/ :

• hestiacp/chapitres/*.md : 14 chapitres + annexe, variables {{IP}}, {{DOMAINE}}…
• hestiacp/skglobalinstitute.conf : variables du VPS en cours d'installation
• hestiacp/build/build.py : générateur PDF (WeasyPrint)
• Commandes vérifiées contre HestiaCP 1.10.4 (code source GitHub, en-têtes # options: des scripts bin/v-*)

Pour suivre le guide : ouvrir le chapitre correspondant, exécuter les commandes une par une en remplaçant les {{VARIABLES}} par les valeurs de skglobalinstitute.conf.

VPS en cours : skglobalinstitute.com

• Domaine : skglobalinstitute.com (registrar OVH)
• Hébergeur : Contabo Cloud VPS 6 — 6 cœurs, 12 Go RAM, 200 Go disque
• IPv4 : 144.91.70.25
• IPv6 : 2a02:c207:2356:8609::1
• Hostname : srv1.skglobalinstitute.com
• Admin panel : skadmin
• Utilisateur hébergement : skglobal
• Utilisateur système (sudo) : scriptshadow
• Email admin : issazana.ia@gmail.com
• Port SSH : 50022
• Port panel : 8083
• Sauvegarde distante : node21-eu.n0c.com (user qmwwranm, port 5022)

Pièges HestiaCP à connaître

Ces points ont été vérifiés dans le code source de HestiaCP 1.10.4 :

• Pare-feu IPv4 seulement : le pare-feu HestiaCP ne filtre pas l'IPv6. Le panel écoute sur [::]:8083. Il faut un pare-feu ip6tables séparé (chapitre 4).
• Pas d'enregistrement AAAA : HestiaCP sert web et mail en IPv4 seulement. Un AAAA ferait échouer Let's Encrypt.
• sudo ne trouve pas les commandes v-* : il faut ajouter /usr/local/hestia/bin au secure_path dans /etc/sudoers.d/.
• Groupe admin préexistant : l'image Contabo Ubuntu 24.04 a déjà un groupe admin et UFW installé. L'installeur HestiaCP refuse les deux.
• Port SSH : le changer après l'installation, pas avant. Sur Ubuntu 24.04, SSH utilise ssh.socket (pas ssh.service).
• Document root Symfony : v-change-web-domain-docroot USER DOM DOM public yes — le yes est indispensable, sinon open_basedir exclut vendor/, var/, config/.
• Zone DNS avant domaine mail : DKIM n'est ajouté au DNS que si la zone existe déjà. Créer la zone DNS d'abord.
• Changement de template DNS : v-change-dns-domain-tpl efface tous les enregistrements ajoutés à la main. Ne le faire qu'immédiatement après la création de la zone.

Environnement à reproduire sur le nouveau VPS

L'utilisateur a configuré cet environnement sur le serveur actuel (z-ana.com). Le reproduire sur le nouveau VPS après l'installation de HestiaCP.

Shell : Zsh + Oh My Zsh + Powerlevel10k

# Installer zsh
sudo apt install -y zsh
chsh -s /usr/bin/zsh

# Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Plugins
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Thème Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k

Dans ~/.zshrc :

ZSH_THEME="powerlevel10k/powerlevel10k"
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
alias cls=clear

Puis lancer p10k configure pour configurer le prompt.

Éditeur : micro

sudo apt install -y micro
sudo update-alternatives --install /usr/bin/editor editor /usr/bin/micro 60
sudo update-alternatives --set editor /usr/bin/micro

Raccourcis micro (~/.config/micro/bindings.json) :

{
    "Alt-/": "lua:comment.comment",
    "CtrlUnderscore": "lua:comment.comment"
}

Terminal multiplexeur : tmux

sudo apt install -y tmux

Outils CLI à installer

sudo apt install -y \
  curl wget git unzip zip rsync \
  htop tmux screen jq ripgrep tree pv pigz zstd p7zip-full \
  neofetch sysstat lsof strace socat whois tcpdump \
  etckeeper debfoster dselect \
  apt-file apt-listchanges apt-rdepends unattended-upgrades \
  fail2ban monit \
  python3 python3-venv \
  ca-certificates gnupg lsb-release dnsutils

Node.js via nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# Relancer le shell, puis :
nvm install --lts

Ajouter dans ~/.zshrc :

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Claude Code

npm install -g @anthropic-ai/claude-code

MOTD personnalisé

Après installation de HestiaCP :

• /etc/update-motd.d/20-neofetch : affiche neofetch à la connexion (config dans /etc/neofetch.conf)
• /etc/update-motd.d/30-updates : script Python qui affiche les mises à jour disponibles (nécessite python3-apt)

Les scripts se trouvent dans le guide chapitre 2 (02-preparation-systeme.md).

Swap et sysctl

• Swap 4 Go, swappiness à 5 (chapitre 2 du guide)
• vm.swappiness = 5 dans /etc/sysctl.d/99-swap.conf

etckeeper + debfoster

• etckeeper suit les modifications de /etc avec git
• debfoster gère la liste des paquets voulus (/etc/keepers)
• Script pre-commit /etc/etckeeper/pre-commit.d/35debfoster (chapitre 2 du guide)

Serveur ISPConfig existant (z-ana.com)

L'ancien serveur (62.169.29.111) utilise ISPConfig et héberge z-ana.com, stlab.ci, djeliba.ci, santeverte.ci, tchefon.ci. La documentation de sa configuration est dans les fichiers 01-prerequis.md à 16-notes-pieges.md à la racine du dépôt.

Le nouveau VPS (skglobalinstitute.com) est un serveur séparé avec HestiaCP. Ne pas confondre les deux.