Install on a GNU/Linux server

gnulinux

These instructions will work for any of the GNU/Linux distributions where Docker is supported and can be installed.

Warning

Only 64 bits distributions are supported. Do not try to install on a 32 bits operating system!

docker

Prerequisites

eLabFTW uses Docker containers. This saves you from dealing with a ton of dependencies and several configuration files, as everything is packed in a container. But we still need a few programs installed before we can get started.

If you don’t have a server, look at the documentation to rent one: Install in the cloud.

Dependencies:

  • curl, to get files from command line (very likely already installed)

  • docker, the container engine

  • docker-compose, the tool to orchestrate containers

  • dialog, to display nice user interface during installation

  • git, the version control system

  • zip, the compression tool (for the backups)

You can have your normal user in the docker group to execute docker commands without sudo (see documentation).

Also if you are running Ubuntu 20.04 with Docker installed as a snap. Uninstall that and install it without snap. See this issue.

Install eLabFTW

Warning

A proper subdomain is required!

  • Install elabctl, a tool to help you manage the elabftw installation:

# get the program (a bash script) and make it executable
curl -sL https://get.elabftw.net -o elabctl && chmod +x elabctl
# add it to a directory in your $PATH
sudo mv elabctl /usr/local/bin/

  • Pre-fill the configuration file:

elabctl install

  • Edit the configuration file:

    Edit the configuration to suit your server setup. For instance, you might want to change the port binding (default is 443 but it might be already used by a traditional webserver). See below for using the container with a reverse proxy.

    If you have set DISABLE_HTTPS=false then you need to configure the TLS certificate. Look at the comments inside the configuration file, they describe the different use cases. In order to request Let’s Encrypt certificates, you need to install certbot. See official Let’s Encrypt documentation for your system. When requesting a new certificate, make sure that port 80 is open (and also port 443 for eLabFTW if it is the one you want to use). Once certbot is installed, the command to use might look like this: certbot certonly --standalone -d elab.example.org.

  • Start eLabFTW:

elabctl start

  • Import the database structure:

docker exec -it elabftw bin/install start

Replace “elabftw” in the command above by the name of the elabftw container if yours is different (for instance if you have several containers running with redis as session handler). You can check this with elabctl status.

  • Register a Sysadmin account:

    Point your browser to https://<your-elabftw-site.org>/register.php (or https://<IP address>/register.php)

Post install

Don’t forget to setup backup, and subscribe to the newsletter!

The next step is to read the Sysadmin guide.

ENJOY! :D

Documentation for advanced setups

Using a TLS certificate from a different provider than Let’sEncrypt

The webserver in the container expects TLS certificates to be in a particular order and format. Make sure that your fullchain.pem file contains certificates in this order: <certificate> <intermediate ca> <root ca>, with PEM encoding.

Using Apache, nginx, HAProxy or traefik as a reverse proxy

All the documentation related to such configurations can be found here.