VMware Install

Learn how to install eramba using VMware - long

  • Episodes7
  • Duration27m 38s
  • LanguagesEN
Episode 3

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 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.

Wrongly set public address

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.

Image switch procedure

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.