Docker Install | Eramba learning portal

Episode 4

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.

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.