Installation

Distribution

The install script and the public Docker images will be published with version 1.0. This page describes the procedure that will apply.

Requirements

• A machine that stays on, on your local network: NAS, mini PC, or Raspberry Pi 4 or 5 running a 64-bit system (Raspberry Pi OS 64-bit, Debian, Ubuntu).
• A fixed IP address for this machine (DHCP reservation on your router): the ESP32s connect to it to reach the MQTT broker.
• About 3 GB of free disk space.

Images are published for PCs (amd64) and 64-bit ARM boards (arm64): Docker picks the right one automatically.

Guided install (recommended)

A script asks the questions one by one, in simple dialogs, and takes care of the rest:

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

It:

1. checks the machine and installs Docker if needed (with your consent);

2. lets you choose the components:

   Component	Default	Role
   API and interface	always	the core of AquasManager
   Mosquitto MQTT broker	✓	untick it if you already have a broker
   Automatic backup	✓	every night at 3 am, adjustable later in the app
   Backups on an NFS share		mounts a NAS share to store backups (see Backups)
   HTTPS (free certificate)		requires a domain name pointing to the machine
   ntfy server		self-hosted ntfy notifications, in addition to the app’s notifications
   IP cameras		go2rtc video service for cameras (Reolink, Tapo, RTSP)

3. asks for the essential settings: server IP address (detected), interface port, administrator account, time zone, the ESP32s’ Wi-Fi and the address range reserved for them (suggested from your network);

4. shows a summary, generates docker-compose.yml and .env (random MQTT and administrator passwords), then starts the application;

5. shows the interface address and the temporary administrator password.

The install goes into /opt/aquasmanager (--dir option for another folder).

The aquasmanager command

The script installs an administration command:

Command	Effect
aquasmanager status	service status and interface address; warns if the IP address changed
aquasmanager logs [api]	live logs
sudo aquasmanager update	back up, then update to the latest version
sudo aquasmanager backup	immediate backup (content and destination set in the app)
sudo aquasmanager reset-password [account]	forgotten password: temporary password (administrator account by default)
sudo aquasmanager start / stop / restart	start, stop, restart
sudo aquasmanager reconfigure	ask the questions again (settings, components), data kept
sudo aquasmanager uninstall	uninstall; data can be kept

Script options

Option	Effect
--dir FOLDER	install folder (default: /opt/aquasmanager)
--plain	plain-text questions, no dialogs
--yes	no questions: defaults or answers file
--answers FILE	pre-filled answers (automated install)
--dry-run	only writes the files, starts nothing
--reconfigure	resume an existing install

Manual install

If you’d rather manage Docker Compose yourself, the install fits in three containers:

• api: the server, with ESPHome built in to compile and flash the ESP32s;
• ui: the web interface (nginx), which also proxies the API under /api;
• mosquitto: the MQTT broker the API and the controllers connect to.

mkdir aquasmanager && cd aquasmanager
# get docker-compose.yml, .env.example and mosquitto/mosquitto.conf
cp .env.example .env
nano .env
docker compose up -d

The .env file

The essential settings:

# Access: interface port and the address you open it at
AQUAS_HTTP_PORT=8080
AQUAS_PUBLIC_URL=http://192.168.1.10:8080

# Administrator account created on first start
AQUAS_DEFAULT_ADMIN_USERNAME=admin
AQUAS_DEFAULT_ADMIN_PASSWORD=ChangeMe123!

# MQTT: same account for the API and the ESP32s
AQUAS_MQTT__USER=aquasmanager
AQUAS_MQTT__PASSWORD=a-long-password
# Server IP as seen by the ESP32s
AQUAS_MQTT__DEVICE_HOST=192.168.1.10

# ESP32 Wi-Fi and network (written into their firmware)
AQUAS_ESP__SSID=MyWifi
AQUAS_ESP__PASSWORD=wifi-password
AQUAS_NETWORK__GATEWAY=192.168.1.1
AQUAS_NETWORK__START=192.168.1.50
AQUAS_NETWORK__END=192.168.1.99

Every option is described in the configuration reference.

First sign-in

Open the address shown at the end of the install (by default http://<server-ip>:8080) and sign in with the administrator account: the temporary password given by the script, or the one set in .env for a manual install. You’ll be asked for a new password on first sign-in.

Note

After 5 failed sign-ins within 15 minutes, from the same address or for the same account, attempts are blocked for 15 minutes.

Continue with the first steps.

HTTPS

The guided install can handle it: tick HTTPS, enter your domain name and an email address, and a free certificate is obtained automatically (Caddy, ports 80 and 443).

Behind your own HTTPS proxy (Traefik, Caddy, Nginx Proxy Manager…), point the proxy at the interface port, then set in .env:

AQUAS_PUBLIC_URL=https://aquas.mydomain.com
AQUAS_AUTH__COOKIE_SECURE=true

Tip

HTTPS is required to install the app on a phone and to receive push notifications: browsers only allow these features on secure sites.

Good to know

• Forgotten password: sudo aquasmanager reset-password shows a temporary password for the administrator account (or reset-password <account> for another account). A new password is asked at sign-in.
• IP address changed (the interface stops answering after the router restarts): aquasmanager status reports it. The simplest fix is to reserve the old address for this machine on the router, then restart it; otherwise sudo aquasmanager reconfigure offers the new address, and the controllers must then be reflashed.
• Controller discovery (mDNS): it doesn’t cross the Docker network by default. Add the ESP32 by hand with its IP address, or switch the api service to network_mode: host. In that case, remove AQUAS_MQTT__HOST and set the server’s IP.
• First flash: it compiles the whole firmware and takes several minutes. Later ones are much faster.
• Data: everything is in ./data, with the SQLite database, the photos and the broker’s data.
• Time: the server stores dates in universal time; the interface shows them in your device’s local time. AQUAS_TIMEZONE is used to work out what’s due “today”.