Troubleshooting

Start by identifying whether the problem is with HTTPS, application startup or the GitHub connection.

#The site does not open securely

Check that the domain’s DNS points to the server and that ports 80 and 443 are reachable. Remove an incorrect AAAA record. Make sure another service is not already using those ports.

docker compose ps
docker compose logs --tail=100 caddy

#The application does not start

docker compose logs --tail=100 app
docker compose logs --tail=100 db

Look for database connection or migration errors. Use the same .env and Compose project as the existing installation. Changing .env does not reset the password in an initialized PostgreSQL database.

Do not remove volumes as a troubleshooting step. Review backups and recovery before replacing data.

#The setup link is missing

Retrieve it on the server:

docker compose exec app gradepush-setup

Keep the output private. Setup cannot be reopened by changing SETUP_TOKEN after the institution has been configured.

#GitHub connection or repository creation fails

Verify that you are using the expected GitHub account, that the account owns the organization and that the correct GitHub App is installed with the required repository access. Check that its public callback and webhook URLs point to your installation.

Check application logs and GitHub’s recent webhook deliveries for errors. If the App was removed or its permissions changed, reconnect it through the organization settings.

#Tests or push activity are missing

Verify that the commit reached the assignment’s designated branch on GitHub. Check that GitHub Actions is enabled and that the run has completed. Look at webhook deliveries and application logs if the run completed but GradePush has not updated.

Before sharing diagnostics, remove tokens, private setup links and student information. Include the GradePush version, the affected action and a sanitized error message.