Docker

Availability

• [SINCE Orbeon Forms 2023.1.3, 2024.1]

• This is an Orbeon Forms PE feature.

Docker images

Multiple Docker images are available from the Orbeon repository on Docker Hub:

• orbeon/orbeon-forms: the Orbeon Forms application running on Tomcat

• orbeon/postgres: a PostgreSQL database prepopulated with the Orbeon Forms database schema

The orbeon/orbeon-forms image can be run as a standalone container, as it contains an SQLite database with demo forms. This is intended for evaluation purposes only, and you will probably want to use another database in production. For this, you can use the orbeon/postgres image, which contains a PostgreSQL database prepopulated with the Orbeon Forms database schema. See the Docker Compose configuration below for an example of how to run Orbeon Forms with PostgreSQL.

Evaluation mode

To create a container from the orbeon/orbeon-forms image, with the embedded SQLite database, run the following docker command:

docker create \
    --name orbeon-forms-with-sqlite \
    -p 8080:8080 \
    -v ~/.orbeon/license.xml:/usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/license.xml \
    orbeon/orbeon-forms:2023.1.4-pe

Make sure to replace ~/.orbeon/license.xml with the path to your license file and to use another port if 8080 is already in use on your machine.

To start the container:

docker start -a orbeon-forms-with-sqlite

You can then access Orbeon Forms using the following URL: http://localhost:8080/orbeon.

While using SQLite, keep in mind that all modifications to the form definitions and data will be stored in the container's filesystem and will be lost if the container is deleted. The file storing the SQLite database is located at /usr/local/tomcat/webapps/orbeon/WEB-INF/orbeon-demo.sqlite inside the container.

Storing SQLite data outside the container

To persist the data outside the container, you can copy the orbeon-demo.sqlite file to the host and mount it inside the container while creating the container from the image, by adding the following argument:

-v /path/to/orbeon-demo.sqlite:/usr/local/tomcat/webapps/orbeon/WEB-INF/orbeon-demo.sqlite

This is not recommended for production use.

This involves creating a first container just to extract the orbeon-demo.sqlite file, then creating a second container with the mounted file. Alternatively, you can also extract the orbeon-demo.sqlite file from the Orbeon Forms WAR file.

Docker Compose configuration

The following docker-compose.yml file can be used to start Orbeon Forms with a PostgreSQL database:

version: '3.8'
services:
  orbeon-forms:
    image: orbeon/orbeon-forms:2023.1.3-pe
    ports:
      - ${ORBEON_TOMCAT_PORT:-8080}:8080
    volumes:
      - ${ORBEON_PROPERTIES_FILE:-./properties-local.xml}:/usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/properties-local.xml
      - ${ORBEON_TOMCAT_CONTEXT_FILE:-./orbeon.xml}:/usr/local/tomcat/conf/Catalina/localhost/orbeon.xml
#      - ${ORBEON_LOG4J2_FILE:-./log4j2.xml}:/usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/log4j2.xml
    secrets:
      - source: license
        target: /usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/license.xml
    depends_on:
      - postgres
    networks:
      - orbeon-forms-and-postgres
  postgres:
    image: orbeon/postgres:2023.1.3-pe
    restart: always
    ports:
      - ${ORBEON_POSTGRES_PORT:-5432}:5432
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${ORBEON_POSTGRES_DB:-orbeon}
      POSTGRES_USER: ${ORBEON_POSTGRES_USER:-orbeon}
      POSTGRES_PASSWORD: ${ORBEON_POSTGRES_PASSWORD:-orbeon}
#      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
#    secrets:
#      - postgres_password
    networks:
      - orbeon-forms-and-postgres
networks:
  orbeon-forms-and-postgres:
    driver: bridge
volumes:
  pgdata:
    name: ${ORBEON_POSTGRES_VOLUME:-orbeon_pgdata}
secrets:
  license:
    file: ${ORBEON_LICENSE_FILE:-~/.orbeon/license.xml}
#  postgres_password:
#    file: ${ORBEON_POSTGRES_PASSWORD_FILE:-postgres_password.txt}

This Docker Compose file is meant as an example and can be customized to fit your needs.

Outside the docker-compose.yml file, you will also need at least three other files:

• the license file (like in the single container case)

• an Orbeon Forms properties file to specify that PostgreSQL must be used instead of SQLite

• a Tomcat context configuration file to specify the PostgreSQL data source

Properties file

The properties-local.xml properties file needs to contain at least the following:

<properties xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:oxf="http://www.orbeon.com/oxf/processors">
    <property as="xs:string"  name="oxf.crypto.password"               value="CHANGE THIS PASSWORD"/>
    <property as="xs:string"  name="oxf.fr.persistence.provider.*.*.*" value="postgresql"/>
    <property as="xs:boolean" name="oxf.fr.persistence.sqlite.active"  value="false"/>
</properties>

Choose a strong password for the oxf.crypto.password property. See Properties for more information about this property and other properties in general.

Tomcat context configuration

The orbeon.xml Tomcat context configuration file needs to contain at least the following:

<Context path="/orbeon">
    <Resource
        name="jdbc/postgresql"
        driverClassName="org.postgresql.Driver"
    
        auth="Container"
        type="javax.sql.DataSource"
    
        initialSize="3"
        maxActive="10"
        maxIdle="10"
        maxWait="30000"
    
        poolPreparedStatements="true"
    
        testOnBorrow="true"
        validationQuery="select 1"
    
        username="orbeon"
        password="orbeon"
        url="jdbc:postgresql://postgres:5432/orbeon?useUnicode=true&amp;characterEncoding=UTF8&amp;socketTimeout=30&amp;tcpKeepAlive=true"/>
</Context>

If you've changed the default PostgreSQL service name, database name, user, password, or port in the Docker Compose configuration, make sure to update the url, username, and password attributes accordingly.

In particular, note that the postgres hostname in the url attribute refers to the name of the PostgreSQL service in the Docker Compose configuration.

Environment variables

Using the example Docker Compose configuration above, you can customize the behavior of the containers by editing the configuration file directly or by using the following environment variables:

Environment variable	Default value	Description
ORBEON_LICENSE_FILE	~/.orbeon/license.xml	Path to the Orbeon Forms license file
ORBEON_PROPERTIES_FILE	./properties-local.xml	Path to the Orbeon Forms properties file
ORBEON_TOMCAT_CONTEXT_FILE	./orbeon.xml	Path to the Tomcat context configuration file
ORBEON_TOMCAT_PORT	8080	Tomcat port
ORBEON_POSTGRES_PORT	5432	PostgreSQL port
ORBEON_POSTGRES_DB	orbeon	PostgreSQL database
ORBEON_POSTGRES_USER	orbeon	PostgreSQL user
ORBEON_POSTGRES_PASSWORD	orbeon	PostgreSQL password
ORBEON_POSTGRES_VOLUME	orbeon_pgdata	Docker volume used to store the PostgreSQL data

The values of those environment variables can be set in a .env file in the same directory as the docker-compose.yml file.

Note that the PostgreSQL password can be specified via a Docker secret file. To do so, uncomment the lines related to postgres_password in the Docker Compose configuration file.

Running the containers using Docker Compose

To start Orbeon Forms with PostgreSQL, run the following command in the directory containing the docker-compose.yml file:

docker compose up

You can also specify the location of the Docker Compose file using the -f option.

JDBC drivers and other databases

The orbeon/orbeon-forms image contains the JDBC drivers for SQLite and PostgreSQL. Other JDBC drivers are not included for licensing reasons. If you need to use another database, you will need to add the JDBC driver to the image.

This can be done by using the following Dockerfile, using MySQL as an example:

FROM orbeon/orbeon-forms:2023.1.3-pe

RUN mkdir -p /tmp/orbeon
WORKDIR /tmp/orbeon

# JDBC driver for MySQL
RUN wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-9.0.0.tar.gz \
    && tar xvfz mysql-connector-j-9.0.0.tar.gz \
    && mv mysql-connector-j-9.0.0/mysql-connector-j-9.0.0.jar /usr/local/tomcat/lib/ 

# Remove SQLite database and JDBC driver (optional)
RUN rm -f /usr/local/tomcat/webapps/orbeon/WEB-INF/orbeon-demo.sqlite \
    && rm -f /usr/local/tomcat/webapps/orbeon/WEB-INF/lib/sqlite-jdbc-*.jar 

# Remove PostgreSQL JDBC driver (optional)
RUN rm -f /usr/local/tomcat/lib/postgresql-*.jar

# Cleanup
RUN rm -rf /tmp/orbeon

The customized image above can then be built using the following command:

docker build -f Dockerfile.mysql -t "orbeon/orbeon-forms-mysql:2023.1.3-pe" .

For further information about configuring Orbeon Forms to use a different database, see Using a relational database.

Logging

By default, Orbeon Forms outputs its logs to the console. To change the logging configuration, you can mount a log4j2.xml file inside the container:

-v /path/to/log4j2.xml:/usr/local/tomcat/webapps/orbeon/WEB-INF/resources/config/log4j2.xml

See Logging for more information.