Troubleshooting

app Container Won't Start

docker compose ps
docker compose logs db
docker compose logs app

Check .env: DB_HOST=db, REDIS_HOST=redis, DB_DATABASE, DB_USERNAME, DB_PASSWORD.

APP_KEY Error

docker compose exec app php artisan key:generate

Migrations Weren't Applied

Dev:

docker compose exec app rm -f storage/.dev-initialized
docker compose restart app

Or manually:

docker compose exec app php artisan migrate --force

Production:

docker compose -f docker-compose.prod.yml exec app php artisan migrate --force

Horizon or Reverb Not Working

docker compose exec app supervisorctl status
docker compose exec app supervisorctl tail -f horizon
docker compose exec app supervisorctl tail -f reverb

Make sure port 9001 is open and REVERB_* / VITE_REVERB_* are set in .env.

Frontend Not Refreshing

docker compose restart frontend

Check VITE_DEV_SERVER_URL in docker-compose.yml.

Mail Not Sending

Check settings in Admin Panel → Mail. See Email Configuration.

storage/ Permission Errors

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

/horizon or /log-viewer Returns 403

Add your email in Admin Panel → System → Access (/admin-panel/system/access) — fields horizonAdmins and logViewerAdmins. Settings are stored in the database; the HORIZON_ADMINS .env variable is not used.

White Screen or 500 in Production

docker compose -f docker-compose.prod.yml logs app
docker compose -f docker-compose.prod.yml exec app php artisan optimize:clear

Media Files Not Loading

docker compose exec app php artisan storage:link

Check limits in Admin Panel → Media (/admin-panel/settings/media). MEDIA_MAX_SIZE and MEDIA_ALLOWED_MIMES in .env are fallback defaults only.

Logs

Source	Path / Command
Laravel	storage/logs/laravel.log
Containers	docker compose logs app
Horizon	http://journalphp.test/horizon → Failed Jobs
Log Viewer	http://journalphp.test/log-viewer
Supervisor	docker compose exec app supervisorctl tail -f <program>

Issue Not Resolved

Create an issue → — attach a log, version (git log --oneline -1), and environment.