Install Nuxeo with the Docker Image

Preamble

This page explains how to install the Nuxeo server with the base Nuxeo Docker image. Yet, to build an application from Nuxeo, most of the time, you will need to customize this image and build your own. For this purpose, we strongly recommend to use an immutable image by building a custom Docker image from the Nuxeo one.

Hyland University

Watch the related course on Hyland University:
Nuxeo Platform Quickstart

×

Requirements

In terms of software, the only requirement to run the Nuxeo Docker image is Docker itself: Java, as well as all the external software, are integrated in the Docker image.

Architecture

The Nuxeo 2021 Docker image, docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021, only supports the amd64 (x86) architecture.

What's in the Nuxeo Image

The Nuxeo Docker image is described by this Dockerfile.

Based on Oracle Linux 7, it includes:

• Azul's Zulu OpenJDK 11.
• A bare Nuxeo server without any package installed.
• A default embedded database, H2 (only valid for testing purposes).
• An embedded Elasticsearch (only valid for testing purposes too).
• Some basic Open Source converters, e.g.: ImageMagick, LibreOffice.
• Chronicle Queue to run the Nuxeo Stream library and services.
• A nuxeo user with the 900 fixed UID.
• The directories required to have the Nuxeo configuration, data and logs outside of the server directory, with appropriate permissions.
• An entrypoint script to configure the server.
• The default recommended volumes.
• The environment variables required by the server, typically NUXEO_HOME and NUXEO_CONF.
• The exposed port 8080.

Running the Image

First, you need to be authenticated in order to pull the Docker image:

docker login docker-private.packages.nuxeo.com -u <username> -p <token_pass_code>

To pull the latest tag of the nuxeo/nuxeo image from the Docker registry and run a container from it, run:

docker run --name nuxeo -p 8080:8080 docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021

The 2021 tag points to the latest release, for instance 2021.0.

To get the latest build, versioned 2021.x.y, you can use the 2021.x tag.

The default command executed when running a container is nuxeoctl console. It can be overridden by specifying an argument to docker run. For instance, to open a bash shell in the container and automatically remove the container when it exits, just run:

docker run -it --rm docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021 bash

For a production setup and general best practices, please read about Mounting Data, Log and Temporary Directories as Volumes.

Configuring the Image at Runtime

Though we encourage to have immutable images configured at build time, in some cases it makes sense to configure a container at runtime. This typically applies to the address and credentials of each back-end store (database, Elasticsearch, S3, etc.) that are specific to a given deployment: development, staging, production, etc.

Configuration Properties

To add or update some configuration properties when running a container from a Nuxeo image, please read the related section about nuxeo.conf.

Environment Variables

Currently, these are the environment variables that are taken into account by a Nuxeo image:

• JAVA_OPTS
• NUXEO_CLID
• NUXEO_CONNECT_URL
• NUXEO_PACKAGES

JAVA_OPTS

Please first have a look at the default JVM settings in the Nuxeo Docker image.

The value of JAVA_OPTS is appended to the JAVA_OPTS property defined in nuxeo.conf at startup.

For instance, to make the Nuxeo Launcher display the JVM settings in the console, run:

docker run --name nuxeo \
  -p 8080:8080 \
  -e JAVA_OPTS=-XshowSettings:vm \
  docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021

NUXEO_CLID

The value of NUXEO_CLID is copied to /var/lib/nuxeo/instance.clid at startup. Please check the Registering your Nuxeo Instance documentation page to create a valid CLID.

For instance, to run a container with a registered Nuxeo instance:

docker run --name nuxeo \
  -p 8080:8080 \
  -e NUXEO_CLID=<NUXEO_CLID> \
  docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021

NUXEO_CONNECT_URL

NUXEO_CONNECT_URL allows to override the default Connect URL at startup.

For instance, to run a container with another Connect URL than the default one:

docker run --name nuxeo \
  -p 8080:8080 \
  -e NUXEO_CONNECT_URL=<NUXEO_CONNECT_URL> \
  docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021

NUXEO_PACKAGES

NUXEO_PACKAGES allows to define a space separated list of Nuxeo packages to install at startup.

For instance, to run a container with the nuxeo-web-ui and nuxeo-drive packages installed:

docker run --name nuxeo \
  -p 8080:8080 \
  -e NUXEO_CLID=<NUXEO_CLID> \
  -e NUXEO_PACKAGES="nuxeo-web-ui nuxeo-drive" \
  docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021

NUXEO_DEV

Setting NUXEO_DEV=true allows to run the Nuxeo image in development mode, meaning:

1. Enable the following configuration properties, see the Configuration Parameters Index (nuxeo.conf) page for more details:

   org.nuxeo.dev=true
   org.nuxeo.rest.stack.enable=true
   # for hot reload
   nuxeo.server.sdk=true
   nuxeo.server.sdkInstallReloadTimer=true
   

2. Override the default command executed when running a container, allowing to execute some nuxeoctl commands inside the container without killing it. This way, you can for instance:

   • Copy some JAR files to the nxserver/bundles directory of the server and restart it with nuxeoctl restart:

     docker run --name nuxeo \
     -p 8080:8080 \
     -e NUXEO_DEV=true \
     docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021
     
     docker ps
     CONTAINER ID   IMAGE
     0eee2751d09d   docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021
     
     docker exec 0eee2751d09d nuxeoctl restart
     

   • Register your instance with nuxeoctl register.

   • Use hot reload with the Nuxeo Dev Tools Extension.
   • Use hot reload with Nuxeo CLI.

3. Activate debugging for the nuxeoctl mp-install command run when installing Nuxeo packages with NUXEO_PACKAGES.

Shell Scripts

To run some shell scripts when starting a container from a Nuxeo image, you can add *.sh files in the /docker-entrypoint-initnuxeo.d directory of the image.

They will be alphabetically sorted and executed at the very end of the ENTRYPOINT, after handling the environment variables. Thus, if you run a container by passing the NUXEO_CLID environment variable, invoking nuxeoctl in such a shell script will work as being registered.