Troubleshooting

When Koha fails to start, it is usually due to misconfiguration:

missing/erroneous required ENV variables: Environment and Configuration
problems connecting to Mysql server
errors in Mysql data
errors in Koha image (sometimes a failed image is pushed to hub, lookup gitref on this repo for clues)

For any error, the best place to start is the docker logs (any STDOUT or STDERR):

docker logs -f myKoha

Mysql server/ Mysql Data

If using external mysql (recommended), it must be running before koha is started. It must also be populated with the right credentials for Koha installer.

Missing KOHA_ADMINUSER or KOHA_ADMINPASS or KOHA_INSTANCE are likely to break Koha webinstaller. Other failures can be:

wrong db version/errors in upgrade/downgrade (downgrading Koha db is near to impossible, upgrades can break installer, but that is more seldom)
koha webinstaller has failed at some stage, either something is missing or apache times out. Try increasing env APACHE_TIMEOUT and click through webinstaller manually

If error is unrecoverable and your data is not important, you can wipe koha db and start over.

make deletedb

or stop and remove mysql server and delete attached data volume:

docker stop koha_mysql && docker rm koha_mysql && docker volume rm koha_mysql_data

Then you can start over with make run

or docker-compose up -f common.yml -f build.yml -d koha_mysql