Troubleshooting
Typical issues and methods you can use to debug
Introduction
In this episode, we'll list the typical install and update issues we encounter in the community and also give you tools and tips on how to deal with them.
Credential Issues
eramba uses a set of default credentials when installed for the first time and on every reset database (default credentials are admin/admin).
If you can not remember your password you can try the "Forgot Password" option on the login screen, if an email was set for your account and the system has email configurations correctly set eramba will send a reset password email.
If you can not remember the admin password and you have not setup email settings then you need to do a backend password reset. This is only possible in on-prem installations, if you are using saas we can do this for you (contact support@eramba.org).
The process to reset your admin password is:
-
enter the eramba docker container
docker exec -it eramba bash
- navigate to the eramba directory
cd /var/www/eramba/app/upgrade
- run the command to reset the database (only available from version 3.20.0)
bin/cake reset_password username password
for example:
bin/cake reset_password admin alphanumeric1
Changing default Ports
By default, the eramba container listens on port 8443 for incoming https connections. The docker comes with a preconfigured port mapping, it will be listening on port 443 and redirecting connections to the eramba container on port 443.
To change the port you will need to:
-
Stop all containers (the first example is for the community version, second for enterprise)
docker compose -f docker-compose.simple-install.yml down
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml down
-
Change the appropriate .yml file and update the ports defined in there
-
Start all containers
docker compose -f docker-compose.simple-install.yml down
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml down
Environmental Variables Issues
eramba uses multiple environmental variables as arguments to the Docker engine, things like MySQL passwords, proxy settings, public URLs, Etc. These environmental variables are defined in the .env file.
To change these variables:
- Stop containers (the first example is for the community version, second for enterprise)
docker compose -f docker-compose.simple-install.yml down
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml down
- Make changes to the .env file
- Start containers (the first example is for the community version, second for enterprise)
docker compose -f docker-compose.simple-install.yml up -d
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml up -d
A typical mistake is to make changes on the .env file while the containers are up and running, they must be stopped before you make any changes.
Database Connection Errors
After a fresh install of eramba, you might sometimes see the following error in docker logs: "Connection to MySQL could not be established"
On some host operating systems other than Ubuntu this error might show up. In order to debug this problem the first step is to review the logs at the mysql container.
docker logs mysql
If you are seeing logs similar to this:
2023-04-07 13:43:54+00:00 [ERROR] [Entrypoint]: mysqld failed while attempting to check config
command was: mysqld --disable-log-bin --verbose --help --log-bin-index=/tmp/tmp.rW4orBIbGp
mysqld: Can't read dir of '/etc/mysql/conf.d/' (OS errno 13 - Permission denied)
Try to add 755 permissions on folder mysql in the docker folder
chmod 755 docker/mysql -R
After that, try you run compose command again (the first example is for the community version, second for enterprise).
docker compose -f docker-compose.simple-install.yml up -d
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml up -d
Missing or invalid CSRF Cookie
At times you might come up with a message: CSRF Invalid Token (or similar) on your browser after login. This error triggers under the following circumstances:
- You have clicked many times something without waiting for the page to load.
- You are logged into eramba, with the same or different user accounts, under the same browser.
- You restored or reset the database.
The easiest way to get rid of the error is of course to avoid the situations mentioned before, typically cleaning all cookies and sessions on your browser will work.
Accessing logs
Logs can be found in settings/error logs and diagnostics, if you can not access this page, you can find them directly when you access eramba container.
docker exec -it eramba bash
Then navigate into the logs directory
cd /var/www/eramba/app/upgrade/logs
from the logs folder, you can tail any logs that you need.