Installation with Docker

Docker is a convenient way to distribute a software package along with its dependencies in a reproducible way. We provide container images as our preferred way of installation for on-premises instances of Txture.

I. Prerequisites

Before you begin, ensure you have the following:

Txture Home Directory Contents: You need the initial contents for the txture_home directory. This is provided by your Txture contact.
Docker Engine: Install Docker Engine. A version > 27 is recommended.
Docker Compose: Install the Docker Compose plugin.

II. Installation Steps

Having fulfilled all prerequisites, follow the steps below to set up and run Txture.

caution

Some commands in this step-by-step guide need to be adjusted and placeholders must be replaced with actual values.

1. Create Docker Volumes

Txture requires persistent storage for its data and for the PostgreSQL database. Create two Docker volumes for this purpose:

For Txture's home directory:
```
docker volume create txture-home
```
For PostgreSQL data:
```
docker volume create txture-postgres
```

2. Populate the `txture_home` Volume

Copy the txture_home contents provided by the Txture team into the txture-home volume. On most systems, the volume is located at /var/lib/docker/volumes/txture-home/_data.

caution

Make sure to copy the contents of your txture_home directory into the _data directory, not the txture_home directory itself.

3. Create Configuration Files

In this step, we will create two configuration files:

An .env file to store your database credentials securely.
A docker-compose.yml file to define the services.

The files must be located in the same directory.
We recommend using either /opt or your home directory (~/).
Once you have chosen your location, create a directory for your files:

mkdir txture

A.) Create your `.env` configuration file

The .env file stores database credentials and lets you define the JVM heap size in MB, the maximum memory the JVM may use. You must adapt the values for your environment, especially the POSTGRES_PASSWORD (see below).

Docker Compose will automatically load this file and substitutes the variables into the docker-compose.yml.

Template for your .env configuration file

# PostgreSQL Credentials
# Replace <your-secure-password> with a strong, alphanumeric (!) password

POSTGRES_USER=txture
POSTGRES_PASSWORD=<your-secure-password>
POSTGRES_DB=txture

# Txture Memory Configuration
# Set to ~75% of available system RAM. Examples:
#  8 GiB RAM -> TXTURE_MEMORY_MB=5500
# 16 GiB RAM -> TXTURE_MEMORY_MB=12000
# 32 GiB RAM -> TXTURE_MEMORY_MB=24000
# 64 GiB RAM -> TXTURE_MEMORY_MB=48000

TXTURE_MEMORY_MB=5500

B.) Create your `docker-compose.yml` configuration file

Next, create the docker-compose.yml file:

Template for your docker-compose.yml configuration file

services:
  txture-db:
    image: postgres:15-bullseye
    container_name: postgres15
    restart: always
    security_opt:
      - no-new-privileges
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - txture-postgres:/var/lib/postgresql/data
    cap_drop:
      - ALL
    cap_add:
      - DAC_READ_SEARCH
      - SETGID
      - SETUID
      - FOWNER
  txture:
    image: 'europe-docker.pkg.dev/txture/production/txture:latest'
    container_name: txture
    restart: unless-stopped
    volumes:
      - txture-home:/opt/txture_home
    command: ['catalina.sh', 'run']
    environment:
      - CATALINA_OPTS=-DtxtureHome=/opt/txture_home -Xmx${TXTURE_MEMORY_MB}m -Xms${TXTURE_MEMORY_MB}m -server -Dio.grpc.netty.shaded.io.netty.transport.noNative=true
      - TXTURE_DB_JDBC_URL=jdbc:postgresql://txture-db:5432/${POSTGRES_DB}?user=${POSTGRES_USER}&password=${POSTGRES_PASSWORD}
    depends_on:
      - txture-db
    ports:
      - 8080:8080
    cap_add:
      - SETGID
      - SETUID
      - CHOWN
      - DAC_OVERRIDE
    cap_drop:
      - ALL
volumes:
  txture-home:
    external: true
  txture-postgres:
    external: true

The volumes section is marked as external: true, which means Docker Compose will use the volumes you created in the previous step instead of creating new ones.

This setup passes the database credentials from the .env file to the postgres container and also constructs the JDBC connection string for the Txture container. This avoids placing secrets directly in the compose file or needing to edit the txture.properties file for the database connection.

4. Restore Database from a Dump

info

This step is required if you want to import pre-configured content such as reports, dashboards, and users provided in the database dump.

If your txture_home directory includes a database dump (e.g., postgres15-bullseye_dump.gz), you can load it into the PostgreSQL container.

First, start only the database service. Run the following command from the directory that contains your docker-compose.yml:

docker compose up -d txture-db

Wait a few seconds for PostgreSQL to initialize, then import the dump: In the command below, the user (-U flag) and database name (the last argument) must match the POSTGRES_USER and POSTGRES_DB values in your .env file:

gzip -cd /path/to/your/postgres15-bullseye_dump.gz | docker exec -i postgres15 psql -U txture txture

tip

If you copied the dump file into the txture-home volume in step 2 and are using the default credentials, the command for most Linux systems will be:

gzip -cd /var/lib/docker/volumes/txture-home/_data/postgres15-bullseye_dump.gz | docker exec -i postgres15 psql -U txture txture

5. Start Txture

Now, start both the Txture and PostgreSQL containers:

docker compose up -d

If your docker-compose.yml file is not in the current directory, use the -f flag to specify its path:

docker compose -f /path/to/your/docker-compose.yml up -d

That's it! Txture will now start, which may take a couple of minutes.

III. Verify the Installation

Once started, you can verify that the containers are running correctly.

Check Container Status
Run docker ps to see the list of running containers. The output should be similar to this:

CONTAINER ID   IMAGE                                                   COMMAND                  CREATED         STATUS         PORTS                    NAMES
3d6e42572e12   europe-docker.pkg.dev/txture/production/txture:latest   "catalina.sh run"        2 minutes ago   Up 2 minutes   0.0.0.0:8080->8080/tcp   txture
b9e3a8aa2600   postgres:15-bullseye                                    "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   5432/tcp                 postgres15

This confirms that both txture and postgres15 containers are up and running.

Access Txture
Txture will be available at http://localhost:8080 in your web browser.

IV. Managing Txture

Here are some useful commands for managing your Txture instance.

View Logs: To view the logs from the Txture container in real-time, use:
```
docker logs -f txture
```
Press Ctrl + C to stop viewing the logs.
Update Txture Image: To pull the latest stable version of Txture, run:
```
docker pull europe-docker.pkg.dev/txture/production/txture:latest
```
To get a specific version, specify the version tag (e.g., :41). After pulling a new image, restart your containers with docker compose up -d to apply the update.

V. Configuration

Database Connection

For new installations (Txture version 41 and later), the recommended way to configure the database connection is by setting the TXTURE_DB_JDBC_URL environment variable, as shown in the docker-compose.yml example above.

However, Txture provides several ways to configure the database connection, which are checked in the following order of priority:

Java System Property: Passed as an argument to the Java command: -Dtxture.db.jdbc.url="...".
Environment Variable: An environment variable named TXTURE_DB_JDBC_URL.
Properties File: A key in the txture.properties file: txture.db.jdbc.url=....

Txture uses the first valid configuration it finds. The first two options are available for Txture 41 and later. For older versions, you must use the txture.properties file.

Memory Allocation

There are two ways to configure memory allocation for Txture. The recommended approach is using the .env file, but for older installations or different setups, you can also configure it directly in the docker-compose.yml.

Using the `.env` File (Recommended)

To adjust the memory available to Txture, modify the TXTURE_MEMORY_MB variable in your .env file. This value sets the maximum and initial JVM heap size in megabytes. For example, to allocate 16 GB:

TXTURE_MEMORY_MB=16000

Modifying `docker-compose.yml`

Alternatively, you can set the memory directly in the docker-compose.yml file. Modify the CATALINA_OPTS environment variable and replace the ${TXTURE_MEMORY_MB} variable with your desired value in megabytes.

For example, to set the memory to 12 GB directly, the line should look like this:

- CATALINA_OPTS=-DtxtureHome=/opt/txture_home -Xmx12000m -Xms12000m -server -Dio.grpc.netty.shaded.io.netty.transport.noNative=true

Outbound Proxy

To route Txture's outgoing traffic through a proxy, add the following to your txture.properties file:

txture.http.outbound.proxy.server.host=http://your.proxy.server:80

This can also be configured in the Txture UI if it's not set in the properties file.

VI. Production Setup Recommendations

important

For Txture production environments, we highly recommend using a reverse proxy like nginx or Caddy. This is crucial to ensure proper TLS encryption for all traffic to your Txture instance.

See our example reverse proxy configuration for more details. Additionally, set up SMTP credentials is recommended to enable email functionalities like notifications, user or survey invites.

VII. Tested System Configurations

The instructions have been tested on the following system configurations, though any modern Linux OS with Docker should work.

CoreOS 1745.7.0 with Docker 18.03.1
Ubuntu 19.04 with Docker 19.03
Ubuntu 18.04 with Docker 19.03.12
Ubuntu 20.04 with Docker 23.0.1
Ubuntu 22.04 with Docker 23.0.1
Ubuntu 22.04 with Docker 27
Ubuntu 24.04 with Docker 27
Fedora 28 with Docker 18.03.1
Fedora 31 with Docker 19.03.5
Fedora 32 with Docker 19.03.8
Fedora 36 with Docker 23.0.1
Fedora 38 with Docker 24.0.6
Fedora 40 with Docker 27
Fedora 41 with Docker 27
RHEL 7
RHEL 8

VIII. FAQ

1. I see a lot of output when starting the container. Is something wrong?
Not necessarily. If you started the container in attached mode, it will display all command-line output. Look for lines containing ERROR. Common errors include a missing txture_home directory or an invalid license file. If there are no errors, your instance is likely running fine.

I. Prerequisites​

II. Installation Steps​

1. Create Docker Volumes​

2. Populate the txture_home Volume​

3. Create Configuration Files​

A.) Create your .env configuration file​

B.) Create your docker-compose.yml configuration file​

4. Restore Database from a Dump​

5. Start Txture​

III. Verify the Installation​

IV. Managing Txture​

V. Configuration​

Database Connection​

Memory Allocation​

Using the .env File (Recommended)​

Modifying docker-compose.yml​

Outbound Proxy​

VI. Production Setup Recommendations​

VII. Tested System Configurations​

VIII. FAQ​