Skip to main content
Version: Edge

How to upgrade from version 5.x to version 6.0

eLabFTW version 6 introduces a few breaking changes impacting container deployment. This page will guide you through the changes.

Overview​

Here are the main changes:

  • container port change
  • container volumes change
  • container user configuration change

Note: this guide assumes usage of docker compose, with hints related to podman quadlets. For other deployments, you will need to adapt the changes to your context.

Making backups​

Make a backup of your configuration file:

# docker
cp /etc/elabftw.yml /etc/elabftw.yml.v5.bak

Obviously, make sure your data backups are also functional and recent before attempting upgrade. But that is valid for any upgrade.

Creating a dedicated user​

Create a dedicated user that will run the services:

useradd --system --no-create-home --shell /usr/sbin/nologin elabftw-worker
id elabftw-worker

Note the user id and group id of that newly created user shown by the second command.

Changes to the configuration file​

In your configuration file (by default /etc/elabftw.yml, start by setting the version of the image:

Docker​

image: elabftw/elabimg:6.0.0

Next, add these lines below image::

# this could look like: user: 995:981
user: <REPLACE WITH ELABFTW-WORKER UID>:<REPLACE WITH ELABFTW-WORKER GID>
read_only: true
tmpfs:
  - /run:mode=755,uid=<REPLACE WITH ELABFTW-WORKER UID>,gid=<REPLACE WITH ELABFTW-WORKER GID>,exec,nosuid,nodev

This will make the container start and run with elabftw-worker user, and a read-only filesystem.

Quadlet​

Only changed/added lines are shown:

[Container]
Image=docker.io/elabftw/elabimg:6.0.0
ReadOnly=true
UserNS=keep-id
HealthCmd=curl --fail --silent --show-error http://localhost:8080/healthcheck
Mount=type=tmpfs,destination=/run,U=true,tmpfs-mode=0755,notmpcopyup

Move the file into ${XDG_CONFIG_HOME:-$HOME/.config}/containers/systemd/ for your user.

See also sections below, adjust volumes accordingly.

Volumes​

The volumes: section needs to be adjusted.

Nginx cache folder​

We will add a folder specific for nginx. First, we create it on the host and allow our elabftw-worker user to write to it:

mkdir -p /var/elabftw/.cache/nginx
chown elabftw-worker:elabftw-worker /var/elabftw/.cache/nginx

Then in the configuration file, under volumes: section:

# docker
  - /var/elabftw/.cache/nginx:/var/cache/nginx
# quadlet
Volume=/var/elabftw/.cache/nginx:/var/cache/nginx:Z

Uploads folder​

Change this line:

- /var/elabftw/web:/elabftw/uploads

To this line:

- /var/elabftw/web:/var/lib/elabftw/uploads

Note: first part might differ on your setup obviously. The main point is that the uploaded files are now expected to be in /var/lib/elabftw/uploads.

Adjust the ownership with our new user:

chown -R elabftw-worker:elabftw-worker /var/elabftw/web

Exports folder​

The exports folder will hold the files generated by the Export function of eLabFTW. It must also be bind-mounted on the host. It is possible that you did not bind-mount that folder previously, as it wasn't a strict requirement. So if you don't see the line, add it.

- /var/elabftw/exports:/var/lib/elabftw/exports

If the line was present, change /elabftw/exports to /var/lib/elabftw/exports.

Adjust the ownership with our new user:

chown -R elabftw-worker:elabftw-worker /var/elabftw/exports

Ports​

In the ports: section, we will need to change internal port 443 to 8080.

Change this line:

ports:
  - '443:443'

To this line:

ports:
  - '443:8080'

It is the right-hand side that needs to be modified: the listening port in the container.

For quadlets, adjust PublishPort if you're using this, or adjust your reverse proxy to use port 8080.

Environment​

Some environment variables are no longer relevant, and should be removed from your configuration. Remove these environment variables:

ENABLE_IPV6
ELABFTW_USER
ELABFTW_GROUP
ELABFTW_USERID
ELABFTW_GROUPID
INDIGO_URL
SILENT_INIT
USE_INDIGO
USE_FINGERPRINTER
FINGERPRINTER_URL
FINGERPRINTER_USE_PROXY

No IPV6 in container​

We removed support for IPv6 in container. You can still use IPv6 to expose the service to the outside world, but the nginx process inside the container doesn't need to listen on IPv6 network stack.

Chem-plugin​

The chem-plugin addon can now be completely removed! It is not useful anymore:

  • indigo/ketcher code is now running in the browser through WASM worker
  • openbabel code for compound fingerprinting is now running in the main container

It is then safe to remove the whole chem-plugin block in your docker compose file.