Troubleshooting

When something goes wrong, look here first.

First-line checks

1. Are all containers running? docker compose ps - every line should say healthy or running.
2. Any Laravel errors? docker compose exec app tail -50 storage/logs/laravel.log.
3. Any container errors? docker compose logs --tail=100 app.
4. Is your DNS pointing at the right IP? dig +short fchat.example.com.
5. Disk full? df -h.

The installer never opens

If ./install.sh times out at "App did not become ready":

docker compose -f docker-compose.installer.yml logs --tail=80 app

Common causes: another service using port 8000 (free it or set INSTALLER_PORT=9000); Docker out of disk; an existing .env with bad credentials (delete it and re-run).

Wizard shows HTTP 500

The wizard runs in installer mode which requires postgres and redis services. Check both are healthy. If you see "This cache store does not support tagging", your CACHE_STORE is set to file or database - change it to redis.

Cannot log in after install

• Double-check the password you typed in the wizard (it was suggested random).
• Make sure you are visiting the admin subdomain: http://admin.your-apex/login.
• From the host: docker compose exec app php artisan tinkerthen \App\Models\SuperAdmin::first()->update(["password" => bcrypt("newpass")]);

Tenant subdomain returns 404 or "Tenant could not be identified"

• The tenant's domain must exist in the central domains table. Check at Super Admin → Tenants → the tenant → Domains.
• For local testing, use localhost as the apex - browsers auto-resolve *.localhost.
• For production, you need a wildcard DNS record and the tenant subdomain must be under your APP_CENTRAL_DOMAINS apex.

Livestream fails to start

• Check that livekit container is up and reachable from app: docker compose exec app curl -fI http://livekit:7880.
• Open ports 7881/TCP, 3478/UDP and 41000-41050/UDP in your cloud firewall.
• If you put Cloudflare in front, set the LiveKit record to DNS only (grey cloud).

Real-time / WebSocket errors in the console

The browser shows "WebSocket connection failed". Check:

• reverb container is running.
• VITE_REVERB_HOST, VITE_REVERB_PORT, VITE_REVERB_APP_KEY are set in .env.
• You rebuilt the frontend after changing those vars: docker compose exec app npm run build.

Emails are not being sent

• .env has MAIL_MAILER=smtp and valid SMTP credentials.
• Test from the host: docker compose exec app php artisan tinker --execute='Mail::raw(...)'.
• Many cloud providers block outbound port 25. Use 587 (TLS) or 465 (SSL).

Permission denied writing storage

docker compose exec app chown -R www-data:www-data storage bootstrap/cache
docker compose exec app chmod -R 775 storage bootstrap/cache

CPU pegged at 100% on a fresh server

If you see unfamiliar containers eating CPU (often a Monero miner), your server has been compromised. Stop everything, take backups, reinstall the OS and apply our prerequisites hardening guide. Never reuse the same root password.