Installation

Prérequis

Une machine allumée en permanence sur votre réseau local : NAS, mini-PC, ou Raspberry Pi 4 ou 5 sous un système 64 bits (Raspberry Pi OS 64 bits, Debian, Ubuntu).
Une adresse IP fixe pour cette machine (réservation DHCP sur votre box) : les ESP32 s’y connectent pour joindre le broker MQTT.
Environ 3 Go d’espace disque libre.

Les images sont publiées pour les PC (amd64) et les cartes ARM 64 bits (arm64) : Docker choisit automatiquement la bonne.

Installation guidée (recommandée)

Un script pose les questions une à une, dans des fenêtres simples, et s’occupe du reste :

curl -fsSL <adresse-du-script>/install.sh -o install.sh
sudo bash install.sh

Il :

vérifie la machine et installe Docker si besoin (avec votre accord) ;

vous laisse choisir les composants :

Composant	Par défaut	Rôle
API et interface	toujours	le cœur d’AquasManager
Broker MQTT Mosquitto	✓	décochez-le si vous avez déjà un broker
Sauvegarde automatique	✓	chaque nuit à 3 h, réglable ensuite dans l’appli
Sauvegardes sur un partage NFS		monte un partage du NAS pour y ranger les sauvegardes (voir Sauvegardes)
HTTPS (certificat gratuit)		demande un nom de domaine qui pointe vers la machine
Serveur ntfy		notifications ntfy auto-hébergées, en plus des notifications de l’appli
Caméras IP		service vidéo go2rtc pour les caméras (Reolink, Tapo, RTSP)

demande les réglages essentiels : adresse IP du serveur (détectée), port de l’interface, compte administrateur, fuseau horaire, Wi-Fi des ESP32 et plage d’adresses qui leur est réservée (proposée d’après votre réseau) ;
affiche un récapitulatif, génère docker-compose.yml et .env (mots de passe MQTT et administrateur tirés au hasard), puis démarre l’application ;
affiche l’adresse de l’interface et le mot de passe administrateur provisoire.

L’installation se fait dans /opt/aquasmanager (option --dir pour un autre dossier).

La commande `aquasmanager`

Le script installe une commande d’administration :

Commande	Effet
`aquasmanager status`	état des services et adresse de l’interface ; signale une adresse IP qui a changé
`aquasmanager logs [api]`	journaux en direct
`sudo aquasmanager update`	sauvegarde puis mise à jour vers la dernière version
`sudo aquasmanager backup`	sauvegarde immédiate (contenu et destination réglés dans l’appli)
`sudo aquasmanager reset-password [compte]`	mot de passe oublié : mot de passe provisoire (compte administrateur par défaut)
`sudo aquasmanager start` / `stop` / `restart`	démarrer, arrêter, redémarrer
`sudo aquasmanager reconfigure`	reposer les questions (réglages, composants), données conservées
`sudo aquasmanager uninstall`	désinstaller ; les données peuvent être gardées

Options du script

Option	Effet
`--dir DOSSIER`	dossier d’installation (défaut : `/opt/aquasmanager`)
`--plain`	questions en texte simple, sans fenêtres
`--yes`	sans questions : valeurs par défaut ou fichier de réponses
`--answers FICHIER`	réponses pré-remplies (installation automatisée)
`--dry-run`	écrit seulement les fichiers, sans rien démarrer
`--reconfigure`	reprendre une installation existante

Installation manuelle

Si vous préférez gérer Docker Compose vous-même, l’installation tient dans trois conteneurs :

api : le serveur, avec ESPHome embarqué pour compiler et flasher les ESP32 ;
ui : l’interface web (nginx), qui relaie aussi l’API sous /api ;
mosquitto : le broker MQTT auquel se connectent l’API et les contrôleurs.

mkdir aquasmanager && cd aquasmanager
# récupérer docker-compose.yml, .env.example et mosquitto/mosquitto.conf
cp .env.example .env
nano .env
docker compose up -d

Le fichier `.env`

Les réglages essentiels :

# Accès : port de l'interface et adresse à laquelle vous l'ouvrez
AQUAS_HTTP_PORT=8080
AQUAS_PUBLIC_URL=http://192.168.1.10:8080

# Compte administrateur créé au premier démarrage
AQUAS_DEFAULT_ADMIN_USERNAME=admin
AQUAS_DEFAULT_ADMIN_PASSWORD=ChangeMe123!

# MQTT : même compte pour l'API et les ESP32
AQUAS_MQTT__USER=aquasmanager
AQUAS_MQTT__PASSWORD=un-mot-de-passe-long
# IP du serveur telle que la voient les ESP32
AQUAS_MQTT__DEVICE_HOST=192.168.1.10

# Wi-Fi et réseau des ESP32 (écrits dans leur firmware)
AQUAS_ESP__SSID=MonWifi
AQUAS_ESP__PASSWORD=mot-de-passe-wifi
AQUAS_NETWORK__GATEWAY=192.168.1.1
AQUAS_NETWORK__START=192.168.1.50
AQUAS_NETWORK__END=192.168.1.99

Toutes les options sont décrites dans la référence de configuration.

Première connexion

Ouvrez l’adresse affichée à la fin de l’installation (par défaut http://<ip-du-serveur>:8080) et connectez-vous avec le compte administrateur : mot de passe provisoire donné par le script, ou celui défini dans .env en installation manuelle. Un nouveau mot de passe vous est demandé à la première connexion.

Poursuivez avec les premiers pas.

HTTPS

L’installation guidée peut s’en charger : cochez HTTPS, indiquez votre nom de domaine et une adresse e-mail, et un certificat gratuit est obtenu automatiquement (Caddy, ports 80 et 443).

Derrière votre propre proxy HTTPS (Traefik, Caddy, Nginx Proxy Manager…), faites pointer le proxy vers le port de l’interface, puis indiquez dans .env :

AQUAS_PUBLIC_URL=https://aquas.mondomaine.fr
AQUAS_AUTH__COOKIE_SECURE=true

Bon à savoir

Mot de passe oublié : sudo aquasmanager reset-password affiche un mot de passe provisoire pour le compte administrateur (ou reset-password <compte> pour un autre compte). Un nouveau mot de passe est demandé à la connexion.
Adresse IP changée (l’interface ne répond plus après un redémarrage de la box) : aquasmanager status le signale. Le plus simple est de réserver l’ancienne adresse pour cette machine sur la box, puis de la redémarrer ; sinon, sudo aquasmanager reconfigure propose la nouvelle adresse, et il faut ensuite reflasher les contrôleurs.
Découverte des contrôleurs (mDNS) : elle ne traverse pas le réseau Docker par défaut. Ajoutez l’ESP32 à la main avec son adresse IP, ou passez le service api en network_mode: host. Dans ce cas, retirez AQUAS_MQTT__HOST et indiquez l’IP du serveur.
Premier flash : il compile tout le firmware et prend plusieurs minutes. Les suivants sont bien plus rapides.
Données : tout est dans ./data, avec la base SQLite, les photos et les données du broker.
Heure : le serveur enregistre les dates en temps universel ; l’interface les affiche à l’heure de votre appareil. AQUAS_TIMEZONE sert au calcul des échéances « du jour ».