Troubleshooting local installation

When the https://<domain> does not work, there are many things that could have wrong. Basic troubleshooting checklist:

1. Is the browser really configured to use http proxy (localhost:3128)?

   • This usually manifests itself by a "Host not reachable" error or similar.

2. Is the proxy working?

   • This usually manifests itself by a "Proxy not reachable" error or similar.

3. Are all containers running? Are they constantly restarting

   • Check the container that dies and analyze its output.

   • On Windows: please make sure that all text files have UNIX line endings (ie "LF" only, not "CRLF"). This is especially important for all shell files (*.sh), configuration files (*.conf) and Dockerfile files.

     • One typical symptom is error message like /usr/bin/env: ‘bash\r’: No such file or directory

   • Error message exec user process caused: no such file or directory on Windows is usually caused by invalid line endings (DOS=crlf instead of UNIX=lf) of crucial files.

     1. Convert all text files in all subdirectories to UNIX line endings.

     2. Destroy all containers: docker down -v

     3. Run the prepare-env.sh script again

     4. Force rebuild of all containers: docker-compose build --no-cache

     5. Start again

4. Check special urls to determine where is the problem:

   • https://<domain>/hcms/v2.0/entity must return 200 OK with a JSON payload

     • 404 error is usually caused by a configuration error or a missing connection to the censhare server. Please check the logs for any errors.

       • Common issue: check that it is possible to connect to the censhare server on a given port (usually 30546). If not, there is a network firewall somewhere and it must be reconfigured.

     • 503 error from haproxy means that the hcms-client contains cannot connect to hcms container.

       • One possible reason: the prepare-env.sh script has been run when the containers already existed and old values are cached somewhere. Try removing all containers (docker-compose down) and force rebuild of all images (docker-compose build --no-cache).

   • https://<domain>/health.txt must return 200 OK with a plaintext payload

     • 404 error means that the hcms-client cannot correctly communicate with hcms

     • 503 error from haproxy means that the node backend failed to start, or started and then later died. There should be some clues in the log of that container.

5. The application works, but any attempt to register new user fails with a generic error.

   • This is usually caused by a missing or invalid SMTP configuration, which means that the attempt to send activation email fails.

   • Since getting fully working SMTP server is often problematic, it is treated as optional in this guide. The user can be activated without the correct link, by someone with sufficient privileges to the censhare server:

     • Un Java client, open the user's asset metadata and remove the asset feature labelled "Portal: User Confirmation Key" (censhare:module.oc.portal.user-confirmation-key)