Update recommendations and troubleshooting

If something goes wrong with the update, it is in almost all cases related to the Apache or Nginx configuration on the host, and NOT Docker and the running containers!

If you are not familiar with your Apache/Nginx configuration (including https), or need to ensure only a minimal downtime, the recommendation will be always to do the painless new installation on a new host and then an migration of your database and files to the new host! Same is true if your old hosts Linux version is no longer supported from it's distribution.

Requirements for the update to succeed

The update operates under the assumption you have NOT changed any of the following:

files or backup directory (/var/lib/egroupware/default/files or /var/lib/egrouware/default/backup)
your database runs on the host AND you use "localhost" as "db_host in header.inc.php
your EGroupware runs under http(s)://your.domain/egroupware (Setup >> Konfiguration >> Webserver URL: /egroupware).
with the exception of MariaDB/MySQL no other service (LDAP, IMAP, PostgreSQL) uses a host-name of localhost

If you changed anything of the above, you either need to change it back to the default locations, or you need to fix your installation after the update. EGroupware will fail after the update without any further changes!

How to migrate your data from an existing 17.1 or older installation

do a new installation as described for the distribution of the new host
enable https using Let's Encrypt following the exzellent instructs from eg. Digital Ocean for Apache or Nginx or take a look at SSL Encryption with Let’s Encrypt in the forum
make a database backup inside your old EGroupware using Administration >> Database backup and restore
rsync the files and backups from the old installation to the new server, run on the new server the following commands:

rsync -av --delete root@<ip-of-old-server>:/var/lib/egroupware/default/ /var/lib/egroupware/default/
chown -R 33:33 /var/lib/egroupware/default

log into the new EGroupware using the generated sysop user and go to Administration >> Database backup and restore and restore the last backup you rsynced to the new server
you can repeat steps 3. to 5. multiple times, until you are ready to use the new system productively

Trouble-shooting a not working installation after the update

What to do if you can not access EGroupware after the update:

run docker ps to check all containers are running:

root@debian:~# docker ps
CONTAINER ID        IMAGE                                           COMMAND                  CREATED             STATUS              PORTS                      NAMES
9f9ad54d14b5        nginx:stable-alpine                             "nginx -g 'daemon of…"   8 days ago          Up 3 minutes        127.0.0.1:8080->80/tcp     egroupware-nginx
d439a0f65fc8        download.egroupware.org/egroupware/epl:latest   "/entrypoint.sh php-…"   8 days ago          Up 3 minutes        9000/tcp                   egroupware
5218213c1d48        containrrr/watchtower                           "/watchtower --sched…"   8 days ago          Up 3 minutes                                   egroupware-watchtower
b705d3fb27f4        rocketchat/rocket.chat:latest                   "bash -c 'for i in `…"   3 weeks ago         Up 3 minutes        127.0.0.1:3000->3000/tcp   rocketchat
f512abc0d03d        mongo:4.0                                       "docker-entrypoint.s…"   3 weeks ago         Up 3 minutes        27017/tcp                  rocketchat-mongo
b8e3dbdf4541        quay.io/egroupware/collabora-key:stable         "/bin/sh -c 'bash st…"   3 weeks ago         Up 3 minutes        127.0.0.1:9980->9980/tcp   collabora-key

(If you only installed EGroupware and not Collabora and Rocket.Chat, you should have only the first 3 containers with names starting with egroupware.

Look at the logs:

cd /etc/egroupware-docker
docker-compose logs -f
root@debian:/etc/egroupware-docker# docker-compose logs
Attaching to egroupware-nginx, egroupware, egroupware-watchtower
egroupware    | Fix APC(u) configuration, set apc.shm_size=128M in /etc/php/7.3/cli/conf.d/20-apcu.ini
egroupware    |
egroupware    | EGroupware successful updated
egroupware    |  * Starting periodic command scheduler cron
egroupware    |    ...done.
egroupware    |
egroupware    | EGroupware successful updated
egroupware    |
egroupware    | EGroupware successful updated
egroupware    |
egroupware    | EGroupware successful updated
egroupware    | [06-Sep-2019 10:41:13] NOTICE: fpm is running, pid 1
egroupware    | [06-Sep-2019 10:41:13] NOTICE: ready to handle connections
egroupware    | [06-Sep-2019 10:41:13] NOTICE: systemd monitor interval set to 10000ms
egroupware-watchtower | time="2019-09-15T07:11:12Z" level=info msg="Waiting for running update to be finished..."

If you don't see the line fpm is running, pid 1 you will will only get a 502 Bad Gateway from Nginx, when you try to connect to EGroupware. The startup of the egroupware container might take a little longer then you expect, as it has to copy the EGroupware sources into a volume which is shared with Nginx, so the webserver can deliver the static content (CSS, JavaScript, images, ...).

If egroupware container alone was restarted without Nginx, Nginx still uses the old IP of egroupware and you get a 502 Bad Gateway. Always restart both: (cd /etc/egroupware-docker; docker-compose restart)

Try to connect to EGroupware container without using the proxy running on the host webserver. We use a tool called curl for these kind of checks. Install it with apt install -y curl (or yum or zypper instead of apt depending on your distribution):

root@debian:/etc/egroupware-docker# curl -i http://localhost:8080/egroupware/
HTTP/1.1 302 Found
Server: nginx/1.16.1
Date: Sun, 15 Sep 2019 07:19:10 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-store, no-cache, must-revalidate
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache
Location: /egroupware/login.php?phpgw_forward=%252Findex.php

If you see the above EGroupware containers are running, it is installed and has a working database connection.

Try accessing EGroupware through the host webserver / proxy possibly with https, if you configured that already:

RalfsMac:epl-19.1 ralf$ curl -i https://testbox9.egroupware.org/egroupware/
HTTP/1.1 302 Found
Date: Sun, 15 Sep 2019 07:26:42 GMT
Server: nginx/1.16.1
Content-Type: text/html; charset=UTF-8
Cache-Control: no-store, no-cache, must-revalidate
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Pragma: no-cache
Location: /egroupware/login.php?phpgw_forward=%252Findex.php
Transfer-Encoding: chunked

If you can see the correct output of 3., but not the above one, something is wrong with your proxy configuration on the host.

EGroupware container can not access MariaDB/MySQL

egroupware    | /usr/bin/php7.3 -d memory_limit=-1 /usr/share/egroupware/setup/setup-cli.php --update 'all,admin,HU4M0zQixh5:fda!'
egroupware    | EGroupware API version 19.1 found.
egroupware    | EGroupware configuration file (header.inc.php) version 1.29 exists and is up to date
egroupware    | Your database is not working! mysqli://egroupware:*********@localhost/egroupware:
egroupware    |
egroupware    | Installation failed --> exiting!
egroupware    |
egroupware    | Retrying EGroupware installation in 3 seconds ...

That situation can happen in a couple of different ways:

RHEL/CentOS does not start or enable the DB by default, you have to do so explicitly!
DB was shut down manually or also updated at the same time as EGroupware

The MariaDB/MySQL socket is bind-mounted into the egroupware container so db_host="localhost" continues to work.

If the DB is not running and therefore the socket is not there when EGroupware container starts, Docker creates a directory with the same name on the host AND inside the container.

Neither of them does recover automatically from that situation!

You have to manually fix it:

cd /etc/egroupware-docker
docker-compose stop egroupware
docker-compose rm -f egroupware
rm -rf /var/{run,lib}/mysql*/mysql*.sock
systemctl start mariadb # or mysqld
systemctl enable mariadb # only necessary for RHEL/CentOS not doing so by installing the DB
systemctl status mariadb
docker-compose up -d