Troubleshooting

Reading the logs, and the failures that actually come up on a self-hosted install.

#Where to look first

bash

# Application errors — start here
docker compose exec orangescrum-app tail -100 logs/error.log

# Container output
docker compose logs -f orangescrum-app

# Is everything running?
docker compose ps

# Database reachable?
docker compose exec orangescrum-postgres pg_isready -U orangescrum

For a manual install, logs/error.log sits in the project root, alongside your web server's own error log.

#Common failures

500 on every page after a config change

Nearly always a stale cache:

bash

docker compose exec orangescrum-app php bin/cake.php cache clear_all

If it persists, logs/error.log will name the missing class or template.

A session cookie problem. Check that FULL_BASE_URL matches the address you are actually using, that SESSION_COOKIE_DOMAIN matches the host, and that SESSION_COOKIE_SECURE is false if you are on plain HTTP — a secure cookie over HTTP is never stored, so the session is lost on every request.

Invitations and password resets never arrive

SMTP is not configured, or is failing silently. Check logs/error.log right after triggering a reset. Also check spam — mail sent directly from a VPS without SPF and DKIM is usually filtered. See Configuration.

Attachments upload but won't download

The files volume is not mounted where the app expects, or permissions are wrong. Confirm the volume exists and that the web server user can read it:

bash

docker volume ls | grep app-files
docker compose exec orangescrum-app ls -la webroot/files

After a partial restore, the database may reference files that were never restored — a database-only restore looks healthy until someone clicks a file.

Uploads fail above a certain size

Raise upload_max_filesize and post_max_size in PHP, and client_max_body_size in Nginx. All three must allow the size; the smallest wins.

The install wizard keeps reappearing

The app writes its installed state into config/. If that directory is not writable, or the Docker config volume was recreated, it cannot tell it has been installed.

Database connection refused

From inside the app container the host is the service name (orangescrum-postgres), not localhost. Also confirm Postgres is healthy — the app has a depends_on healthcheck, so a restarting app container often means the database never came up.

Locked out — no working admin

bash

docker compose exec orangescrum-app php bin/cake.php change_admin_password

Disk full

Attachments and PostgreSQL data are the two that grow. Check both:

bash

docker system df -v

Old images and stopped containers are worth pruning, but never with -v unless you are certain which volumes go with it.

#Health checks worth automating

🌐HTTP

The app container already has a healthcheck. Alert on it going unhealthy.

💾Disk

Alert at 80% on the volume holding attachments and the database.

🕐Backup freshness

Alert if last night's dump is missing or suspiciously small.

🚨Error rate

Watch logs/error.log for new entries rather than reading it after a complaint.

#Reporting a bug

The Community Edition is version 0.1.0 — bugs are expected. A useful report has:

What you did, what happened, what you expected
The relevant lines from logs/error.log
Your version (VERSION.txt), PHP version and whether you use Docker
Whether it reproduces on a fresh install

Open it on GitHub, and see Contributing if you want to fix it yourself.