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

Changing the network address-range of Docker

Docker and docker-compose creates (internal) networks by default in the 172.[17-31].0.0 range. If you use this range already for existing networks you need to change the default BEFORE installing EGroupware, as you wont be able to reach EGroupware from 172.17+ networks!

To move all Docker IP addresses / networks eg. to 172.22.0.0/16 you need to do the following: Create the file /etc/docker/daemon.json with the following content:

{
  "default-address-pools":
  [
    {"base":"172.22.0.0/16","size":24}
  ]
}

Then you need to restart the Docker daemon, if you already installed it: systemctl restart docker

In case you already installed EGroupware you need to delete all containers and networks, as the above only works for newly created networks NOT for the existing ones:

for dir in /etc/egroupware-*
do
    cd $dir
    docker-compose stop
    docker-compose rm -f
done
docker system prune
for dir in /etc/egroupware-*
do
    cd $dir
    docker-compose up -d
done

If your Linux server needs to use a proxy to access the internet

I take you already configured your Linux system so it can install and update packages via your proxy.
Docker needs to have the proxy configured to be able to pull images
EGroupware can also use a proxy to eg. check for an update. Proxy settings are in Setup (https://example.com/egroupware/setup/) upper login under: Edit current configuration > Host information

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
a6cb25ad6b2d        nginx:stable-alpine                           "/docker-entrypoint.…"   29 minutes ago      Up 29 minutes                     127.0.0.1:8080->80/tcp     egroupware-nginx
290fd2abed44        phpswoole/swoole:latest                       "/entrypoint.sh"         29 minutes ago      Up 29 minutes                                                egroupware-push
d8febd271620        download.egroupware.org/egroupware/epl:20.1   "/entrypoint.sh php-…"   29 minutes ago      Up 29 minutes                     9000/tcp                   egroupware
1a6a24e51144        containrrr/watchtower                         "/watchtower --sched…"   5 weeks ago         Up 2 hours                        8080/tcp                   egroupware-watchtower
bbc8657ad981        rocketchat/rocket.chat:latest                 "docker-entrypoint.s…"   2 hours ago         Up About a minute                 127.0.0.1:3000->3000/tcp   rocketchat
1bc8a8f0eae8        mongo:4.0                                     "docker-entrypoint.s…"   2 hours ago         Restarting (100) 38 seconds ago                              rocketchat-mongo
0a1d2b2257c8        quay.io/egroupware/collabora-key:latest       "/bin/sh -c 'bash st…"   2 hours ago         Up 2 hours                        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 4 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

This should not happen any more with 20.1, unless you updated from 19.1, as 20.1 runs MariaDB 10.4 in a container for new installations.

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

Docker on Btrfs

Running Docker on a Btrfs partition causes a problem: Old images are not deleted and the partition fills up over time. Here is a (long) thread on this topic:

https://github.com/moby/moby/issues/27653

So it is currently (12.2019) not recommended to run Docker on Btrfs. Otherwise, regular checks and manual cleanup are necessary.

If someone has a solution, we ask for feedback in the forum.