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.
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.
Architectures
The Nuxeo 2023 Docker image, docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023
, supports multiple platforms: it contains variants for the amd64
(x86
) and arm64v8
architectures.
When pulling this image, Docker automatically selects the variant that matches your OS and architecture. For instance, if you're running on:
- Linux (AMD64), you'll get the
amd64
variant. - Apple Silicon M1 (ARM64), you'll get the
arm64
variant.
The arm64
variant doesn't include the LibreOffice converter. Unfortunately, there is currently no LibreOffice RPM package available in a recent version for Rocky Linux (the base OS) in the arm64
architecture. Consequently:
arm64
variant of the Nuxeo 2023 Docker image is not production-ready. It is for development purpose only. When running docker pull docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023
or docker run docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023
, if you're running on an ARM64 architecture (typically Apple Silicon M1), the pulled Docker image doesn't include LibreOffice. Thus, the conversion features relying on LibreOffice won't be available, typically converting Office documents to PDF.
--platform
option, for instance to pull the amd64
variant: docker pull docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023 --platform=linux/amd64
What's in the Nuxeo Image
The Nuxeo Docker image is described by this Dockerfile.
Based on Rocky Linux 9.4, it includes:
- Azul's Zulu OpenJDK 17.
- 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.
- A
nuxeo
user with the900
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
andNUXEO_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:2023
The 2023
tag points to the latest release, for instance 2023.0.
To get the latest build, versioned 2023.x.y
, you can use the 2023.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:2023 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:2023
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:2023
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:2023
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:2023
NUXEO_DEV
Setting NUXEO_DEV=true
allows to run the Nuxeo image in development mode, meaning:
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
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 withnuxeoctl restart
:docker run --name nuxeo \ -p 8080:8080 \ -e NUXEO_DEV=true \ docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023 docker ps CONTAINER ID IMAGE 0eee2751d09d docker-private.packages.nuxeo.com/nuxeo/nuxeo:2023 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.
Activate debugging for the
nuxeoctl mp-install
command run when installing Nuxeo packages withNUXEO_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.