The installer prints a plain-English message when a step fails, along with the exact command to investigate. Here are the handful of issues that account for almost everything, and how to fix each. Run all commands from inside the portal folder you cloned into.
Install failed partway through
Just run it again — ./install.sh is idempotent and won't undo work it already did. To see the full build output:
./install.sh --verbose
"The app container did not become healthy"
Usually the database didn't start or a value is wrong. Look at the logs for the real error:
docker compose logs app
docker compose logs postgres
No padlock / "your connection is not private" that never clears
Your domain's DNS A-record isn't pointing at this server yet, so Let's Encrypt can't issue a certificate. Confirm what your domain resolves to, then wait for DNS to update:
dig +short portal.youragency.com # should print your server's public IP
"Port already in use" / containers won't start
Something else on the server is holding port 80 or 443 (a stray Apache/Nginx, or an old install). Find it, then stop it or use a clean server:
docker compose ps
sudo ss -tlnp | grep -E ':80|:443'
SMTP test fails in the wizard
- Double-check your SMTP credentials (case-sensitive passwords are a common culprit).
- Confirm the host is reachable:
telnet smtp.example.com 587(or your port). - Many VPS providers block outbound ports 25/465/587 — see Set up email sending.
Still stuck?
Capture the output of ./install.sh --verbose and docker compose logs and send both to support — together they almost always pinpoint the problem.