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
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 up -d
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml up -d
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 something many times 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.
When accessing Eramba, attempting to save any settings results in a greyed-out screen, and the logo fails to load. This issue is typically caused by an incorrect public address setting in the .env file. It is essential to configure this setting prior to deploying the containers. If changes are needed afterward, please remember to stop the containers and redeploy them accordingly.
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.
From time to time there is a need for an update on the docker level of the application (when there is a need for PHP update or Apache update etc.). In this case, there needs to be an 'image switch' procedure done.
- Community users:
1. Stop and remove all containers, not removing volumes or any user data
docker compose -f docker-compose.simple-install.yml down
2. List all available volumes in your docker-engine
docker volume ls
3. You need to remove the _app volume, by default it is called docker_app
docker volume rm docker_app
4. Remove eramba images stored in your docker-engine
docker image rm ghcr.io/eramba/eramba:latest
5. Pull desired image
docker pull ghcr.io/eramba/eramba:{tag}
* substitute {tag} with desired version
!!! Please keep in mind that you only can do updates step by step, it is not possible to jump to the latest version with the following procedure !!!
for example, my current installation is on version 3.23.0 and I will do an update to 3.23.1:
docker pull ghcr.io/eramba/eramba:3.23.1
6. Tag the pulled image as the latest
docker tag ghcr.io/eramba/eramba:{tag} ghcr.io/eramba/eramba:latest
7. Start the containers again
docker compose -f docker-compose.simple-install.yml up -d
- Enterprise users:
The procedure is very similar to community but you have to get an enterprise image. These images need to be secured and we will build them for you specifically. Please follow carefully step 5.
1. Stop and remove all containers, not removing volumes or any user data
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml down
2. List all available volumes in your docker-engine
docker volume ls
3. You need to remove the _app volume, by default it is called docker_app
docker volume rm docker_app
4. Remove eramba images stored in your docker-engine
docker image rm ghcr.io/eramba/eramba:latest
docker image rm ghcr.io/eramba/eramba-enterprise:latest
5. Write to support@eramba.org to get {tag} enterprise image.
* substitute {tag} with desired version
!!! Please keep in mind that you only can do updates step by step, it is not possible to jump to the latest version with the following procedure !!!
6. Load a new enterprise image into the docker-engine
- for AMD image
docker load --input eramba-enterprise-{tag}-amd64.tar
- for ARM image
docker load --input eramba-enterprise-{tag}-arm64.tar
7. Tag image as the latest
docker tag ghcr.io/eramba/eramba-enterprise:{tag} ghcr.io/eramba/eramba-enterprise:latest
8. Start the containers again
docker compose -f docker-compose.simple-install.yml -f docker-compose.simple-install.enterprise.yml up -d
PDF Export Errors
An error such as “An Internal Error Has Occurred” may appear when attempting to export a PDF.
In order to debug this problem the first step is to review the logs in Settings > Error Logs and Diagnostics.
If you notice logs resembling the following:
Failed to load https://eramba:8443/limitless_theme/css/icons/icomoon/styles.css (ignore)
Warning: Failed to load https://eramba:8443/limitless_theme/css/bootstrap.css (ignore)
Warning: Failed to load https:// eramba:8443/limitless_theme/css/core.css (ignore)
Warning: Failed to load https:// eramba:8443/limitless_theme/css/components.css?ver=20200327 (ignore)
Warning: Failed to load https:// eramba:8443/limitless_theme/css/colors.css (ignore)
Warning: Failed to load https:// eramba:8443/css/report-blocks-grid.css (ignore)
Warning: Failed to load https:// eramba:8443/css/eramba.css?app_v=3.24.2 (ignore)
This indicates that the server hosting Eramba is unable to establish a connection with itself, interrupting the PDF generation process. It is necessary to enable the server to connect to its own services.