Troubleshooting

Diagnosing common errors when installing and running JournalPHP.

Commands are given for the local environment. In production, add -f docker-compose.prod.yml after docker compose.

The app container does not start

docker compose ps
docker compose logs db
docker compose logs app

Check DB_DATABASE, DB_USERNAME and DB_PASSWORD in .env.

Migrations were not applied

Run new migrations:

docker compose exec app php artisan migrate --force

If the database was recreated empty, remove the storage/.dev-initialized marker and restart app: migrations will run together with the seed data.

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

Queues, scheduler or WebSocket do not work

Horizon, the scheduler and Reverb run via Supervisor inside the app container:

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

For WebSocket, check that port 9001 is reachable and that the REVERB_* and VITE_REVERB_* variables in .env are filled in and consistent — see Configuration.

The frontend does not update

docker compose logs frontend
docker compose restart frontend

Vite should respond at http://localhost:5173.

Emails are not sent

Check the email settings and storage/logs/laravel.log — see Email.

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

Only users listed in Admin Panel → System → Access get access — see Service URLs.

White screen or error 500

docker compose logs app
docker compose exec app php artisan optimize:clear

Error details are in storage/logs/laravel.log.

Media files are not uploaded or displayed

docker compose exec app php artisan storage:link

File size and type limits and external storage credentials are set in Admin Panel → Settings → Interface → Media — see Site settings.

Search finds nothing

With Algolia or Meilisearch, check the keys and run index synchronization — see Search. Synchronization runs in the queue, so Horizon must be running.

Logs

• Laravel: storage/logs/laravel.log or /log-viewer
• Containers: docker compose logs <service>
• Queues: /horizon
• Supervisor: docker compose exec app supervisorctl tail -f <program>
• Frontend: the browser console

Access to /horizon and /log-viewer is described in Service URLs.

If the problem persists, open an issue.