Txture Installation

A Txture on-premise deployment is rather straightforward to set up. Besides Txture itself, only a PostgreSQL database is needed. Nevertheless, make sure you meet the requirements described in System Requirements.

The deployment can be done with Docker or Kubernetes:

Deployment with Docker
Deployment on Kubernetes

Deployment 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-premise instances of Txture.

Prerequisites

There are only a few prerequisites for running a Txture instance using Docker:

Initial contents for txture_home (typically provided by Txture)
Installed docker (a version > 23.01 is recommended)
docker-compose - either as the standalone version or the newer docker plugin

Quick Setup

First you have to prepare a directory in which Txture stores all information. This directory is called the txture_home and must be mounted to the docker container in order for it to properly work. The contents of the directory are detailed in the txture_home documentation. Typically this will be provided to you by the Txture support team. Create a docker volume for the txture_home like this:

docker volume create txture-home

Proceed to copy the contents of the directory to the volume. On most docker systems the volume will be located at /var/lib/docker/volumes/txture-home/_data

Make sure to only copy the contents of the txture_home directory into the _data directory rather than the entire directory.

Create a docker volume to store the PostgreSQL data using the following command:

docker volume create txture-postgres

Create a docker-compose.yml file similar to the following one:

version: '3.4'

services:
  txture-db:
    image: postgres:15-bullseye
    container_name: postgres15
    restart: always
    security_opt:
      - no-new-privileges
    environment:
      POSTGRES_USER: {{txture_postgres_user}}
      POSTGRES_PASSWORD: {{txture_postgres_password}}
      POSTGRES_DB: {{txture_postgres_db_name}}
    volumes:
      - txture-postgres:/var/lib/postgresql/data
    cap_drop:
      - ALL
    cap_add:
      - DAC_READ_SEARCH
      - SETGID
      - SETUID
      - FOWNER
  txture:
    image: "eu.gcr.io/txture-docker/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 -Xmx8000m -Xms8000m -server -Dio.grpc.netty.shaded.io.netty.transport.noNative=true
    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

You can see that two services are described in this docker compose file. One is txture, the other one a PostgreSQL 15 container.

Note also the volume section in this docker compose file. It specifies two volumes, txture-home and txture-postgres with the parameter external being true. This means that docker-compose does not create these volumes and they have to be created manually beforehand (it was done in the previous two steps).

In the above compose file, there are a couple of values in {{ curly brackets }}. These are placeholders and need to be filled. They define the connection credentials used between Txture and the PostgreSQL server. Therefore they can be set arbitrarily, but have to match between the docker-compose.yml file and the connection string in the txture.properties file. For the above example, the following connection string in txture.properties can be used:

txture.db.jdbc.url=jdbc:postgresql://txture-db:5432/{{txture_postgres_db_name}}?user={{txture_postgres_user}}&password={{txture_postgres_password}}

Additionally, an Xmx setting has been configured in this compose file for the Txture service. This is the amount of RAM Txture is allowed to use.

Start the whole setup using the following command:

docker-compose up -d

If your compose-file is in a different location, you can also use -f the define where it is located:

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

That's it! Txture will now start, which can take up to two minutes and will then be available at http://localhost:8080.

PostgreSQL Connection String

The JDBC connection string for the PostgreSQL database is typically in the form:

txture.db.jdbc.url=jdbc:postgresql://txture-db:5432/{{txture_postgres_db_name}}?user={{txture_postgres_user}}&password={{txture_postgres_password}}

There are three options to set the JDBC URL (from highest to lowest priority):

As a an argument to the java command with -Dtxture.db.jdbc.url="...". Tomcat logs this to console on startup (key and value).
As an environment variable named TXTURE_DB_JDBC_URL (e.g. export TXTURE_DB_JDBC_URL="...").
As a key in the txture.properties file: txture.db.jdbc.url="..."

Txture will check them in the given order and take the first one it finds (e.g. if there is a program argument, it will use it. If there isn’t, it will check for an environment variable, and finally it will check the txture.properties file).

Note that the first two options only work for Txture 41 and later.

Production setups

For a production setup we recommend to use nginx or Caddy as a reverse proxy to provide TLS.

Useful commands

You can read the log output of Txture using docker logs -f txture. The -f tells docker to keep following the logs. Control + C stops displaying the logs.
One can check the status of docker containers using the command docker ps. This should give an output similar to this:
```
    [user@localhost ~]$ docker ps
    CONTAINER ID        IMAGE                                  COMMAND             CREATED              STATUS              PORTS                    NAMES
    3d6e42572e12        eu.gcr.io/txture-docker/txture:latest  "catalina.sh run"   About a minute ago   Up About a minute   0.0.0.0:8080->8080/tcp   txture
```
The container with the ID 3d6e42572e12 is running the Txture image in the latest version and has the name "txture". It is also visible here that port 8080 on the host machine was mapped to 8080 in the container. You can therefore access your docker instance at http://localhost:8080. You are all set!
Pull the current Txture image using the following command:
```
docker pull eu.gcr.io/txture-docker/txture:latest
```
This will always give you the latest stable image of Txture. Optionally, you can can also use eu.gcr.io/txture-docker/txture:34 to download a specific version (34 in this case).

Tested System Configurations:

The following list is a non-exhaustive list of tested configurations. Very likely, any modern Linux OS with Docker works perfectly fine.

The instructions have been tested on the following system configurations:

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
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
RHEL 7
RHEL 8

FAQ Deployment with Docker

I started the Txture docker container and I receive a lot of output! Is something going wrong?

Not necessarily. Maybe you started the docker container in the attached mode (purposely), meaning any output to the command line is displayed. You may want to look out for lines containing the tag*'ERROR'.* Typical errors include a missing txture_home directory or invalid license files. If no errors are present, your instance is running fine.

How can I change the amount of memory used by Txture (Xmx setting)?

Txture looks for an environment variable called CATALINA_OPTS on startup. A default value for this variable is set for the container, but can be changed using the usual way to modify environment variables in your container runtime. Use the following setting to change the memory to 8000 MB:

CATALINA_OPTS=-DtxtureHome=/opt/txture_home -Xmx8000m -server

Can I use a proxy for Txture's traffic to the outside?

Yes, you can. This is a setting in the txture.properties file, or, alternatively, in the admin area of the Txture instance. Note, that you can only change it in the UI if the property is not set in the properties file. A typical example could look like this:

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

In the above example, all traffic will be routed through the proxy your.proxy.server on port 80. You can configure both the HTTP and HTTPS (default) protocols in the above setting.

Deployment on Kubernetes

Since Txture is offered as a container, it can be operated on Kubernetes easily. The following guide details some steps to install Txture on a Kubernetes cluster.

Prerequisites

This guide has a couple of prerequisites and assumptions:

The configuration files assume that the PostgreSQL server will be run as a container alongside Txture. This is not strictly necessary as any other deployment of a PostgreSQL server (e.g. DBaaS or central service) works equally well. If that is the case, remove the PostgreSQL section from the following suggested configuration files.
A working Kubernetes cluster and kubectl set up locally.
Initial contents for txture_home (typically provided by Txture)

Configuration files

The first configuration file contains the workloads and service needed for Txture and the PostgreSQL database:

apiVersion: v1
kind: Service
metadata:
  name: txture
spec:
  ports:
  - port: 8080
  selector:
    app: txture
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: txture
spec:
  selector:
    matchLabels:
      app: txture
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: txture
    spec:
      containers:
      - image: postgres:15-bullseye
        name: postgres15
        args: ["-c", "log_destination=jsonlog"]
        env:
        # Use secret in real usage
        - name: POSTGRES_USER
          value: txture
        - name: POSTGRES_PASSWORD
          value: pleaseuseaproperypasswordhere
        - name: POSTGRES_DB
          value: txture
        ports:
        - containerPort: 5432
          name: txture-db
        volumeMounts:
        - name: txture-db-volume
          mountPath: /opt/txture-postgres
      - image: eu.gcr.io/txture-docker/txture:40
        name: txture
        command: ["/bin/sh", "-c"]
        args: ["until [ -f /opt/txture_home/txture.properties ]; do sleep 5; done && catalina.sh run"]
        env:
        - name: CATALINA_OPTS
          value: -DtxtureHome=/opt/txture_home -Xmx8000m -Xms8000m -server -Dio.grpc.netty.shaded.io.netty.transport.noNative=true
        resources:
          limits:
            memory: "9000Mi"
        ports:
        - containerPort: 8080
          name: txture
        volumeMounts:
        - name: txture-home
          mountPath: /opt/txture_home
      volumes:
      - name: txture-db-volume
        persistentVolumeClaim:
          claimName: txture-db-claim
      - name: txture-home
        persistentVolumeClaim:
          claimName: txture-home-claim

In addition, two persistent volume claims will need to be created (one for Txture, one for PostgreSQL):

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: txture-home-claim
spec:
  storageClassName: standard-rwo
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: txture-db-claim
  namespace: default
spec:
  storageClassName: standard-rwo
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Please note that the storageClassName will likely need to be adapted to your Kubernetes clusters. The values provided work for Google Kubernetes Engine (GKE).

Deploying the pods

Put the two .yaml files in a single directory (e.g. txture-kubernetes) of your choice. The .yaml files will create one service and two persistent volumes (one for the txture_home folder, the other for the postgres database). You can configure the database password and user in the txture.yaml file.

Once you're happy with the configuration, deploy everything with

kubectl apply -f txture-kubernetes/

Txture will not start until you upload the txture_home to the volume. Specifically, there is a check before the startup that waits until the file /opt/txture_home/txture.properties is present.

Uploading your txture_home directory

First, make sure the configuration in the txture.properties file is correct. Most importantly, make sure that the JDBC connection string matches your PostgreSQL configuration. You can then upload the txture_home folder using kubectl cp.

In order to be able to upload, you'll need to get the pod name first. You can fetch that information with

kubectl get pods

which should show you an output such as this

NAME                                                READY   STATUS    RESTARTS      AGE
txture-5bdb8cd8d5-9zn6z                             1/1     Running   0             32m

You can then copy the folder to the txture container running in the pod with

kubectl cp txture_home/ txture-5bdb8cd8d5-9zn6z:/opt/ -c txture

Once the files required by txture are uploaded, it will start. This might take a few minutes. You can check the logs of your Kubernetes workloads to see the progress.

Accessing your Txture instance

Once Txture has started successfully, you can access it using kubectl port-forwarding. The port of Txture is set in the txture.yaml Kubernetes file. You can then forward the port using the pod name once more.

kubectl port-forward txture-5bdb8cd8d5-9zn6z 8080:8080

This will map the service's port to your localhost. You can then access the Txture instance at localhost:8080 and log in using the password you set.

Production setup

While the above sets up a Txture instance, you might want to add some more configurational details and additions. They have been left out in the above example for simplicity, but production setups might require one or more of these:

Reverse proxy or ingress to handle TLS
Security settings such as CAP_DROP

Deployment with Docker​

Prerequisites​

Quick Setup​

PostgreSQL Connection String​

Production setups​

Useful commands​

Tested System Configurations:​

FAQ Deployment with Docker​

I started the Txture docker container and I receive a lot of output! Is something going wrong?​

How can I change the amount of memory used by Txture (Xmx setting)?​

Can I use a proxy for Txture's traffic to the outside?​

Deployment on Kubernetes​

Prerequisites​

Configuration files​

Deploying the pods​

Uploading your txture_home directory​

Accessing your Txture instance​

Production setup​

Deployment with Docker

Prerequisites

Quick Setup

PostgreSQL Connection String

Production setups

Useful commands

Tested System Configurations:

FAQ Deployment with Docker

I started the Txture docker container and I receive a lot of output! Is something going wrong?

How can I change the amount of memory used by Txture (Xmx setting)?

Can I use a proxy for Txture's traffic to the outside?

Deployment on Kubernetes

Prerequisites

Configuration files

Deploying the pods

Uploading your txture_home directory

Accessing your Txture instance

Production setup