Kubernetes deployment

Create a dedicated namespace for Txture:

kubectl create namespace txture

Create a file named txture.env on your local machine. This file controls credentials and sizing, similar to the .env file in the Docker guide. Refer to the System Requirements to determine the correct sizing for your workload.

# Database Credentials
POSTGRES_USER=txture
POSTGRES_PASSWORD=YOUR_SECURE_PASSWORD_HERE
POSTGRES_DB=txture

# PostgreSQL hostname (use the bundled service name, or set to your external database host)
POSTGRES_HOST=postgres

# Txture Sizing (32GB RAM / 10 Cores example)
TXTURE_MEMORY_LIMIT=32Gi
TXTURE_MEMORY_REQUEST=16Gi
TXTURE_CPU_REQUEST=2000m
TXTURE_CPU_LIMIT=10000m

# PostgreSQL Sizing
POSTGRES_MEMORY_REQUEST=256Mi
POSTGRES_MEMORY_LIMIT=1Gi
POSTGRES_CPU_REQUEST=100m
POSTGRES_CPU_LIMIT=1000m

# Storage
TXTURE_STORAGE_SIZE=130Gi
POSTGRES_STORAGE_SIZE=20Gi

Create a file named txture-manifests.yaml with the following content. This file defines all resources (Secret, PVCs, Deployments, Services) and uses ${VARIABLE} placeholders that are filled in by envsubst during deployment. You generally do not need to edit this file.

# Database Credentials Secret
apiVersion: v1
kind: Secret
metadata:
  name: txture-db-credentials
  namespace: txture
stringData:
  POSTGRES_USER: "${POSTGRES_USER}"
  POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
  POSTGRES_DB: "${POSTGRES_DB}"
---
# PersistentVolumeClaims
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: txture-home
  namespace: txture
spec:
  accessModes: [ReadWriteOncePod]
  resources:
    requests:
      storage: ${TXTURE_STORAGE_SIZE}
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: txture-postgres
  namespace: txture
spec:
  accessModes: [ReadWriteOncePod]
  resources:
    requests:
      storage: ${POSTGRES_STORAGE_SIZE}
---
# PostgreSQL Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: txture
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: postgres
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 999
        fsGroup: 999
      containers:
      - name: postgres
        image: postgres:15-bullseye
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop: ["ALL"]
        env:
        - name: POSTGRES_USER
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_USER
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_PASSWORD
        - name: POSTGRES_DB
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_DB
        - name: PGDATA
          value: /var/lib/postgresql/data/pgdata
        ports:
        - containerPort: 5432
          name: postgres
        volumeMounts:
        - name: postgres-storage
          mountPath: /var/lib/postgresql/data
        resources:
          requests:
            memory: ${POSTGRES_MEMORY_REQUEST}
            cpu: ${POSTGRES_CPU_REQUEST}
          limits:
            memory: ${POSTGRES_MEMORY_LIMIT}
            cpu: ${POSTGRES_CPU_LIMIT}
        readinessProbe:
          exec:
            command: ["/bin/sh", "-c", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          exec:
            command: ["/bin/sh", "-c", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
          initialDelaySeconds: 15
          periodSeconds: 20
      volumes:
      - name: postgres-storage
        persistentVolumeClaim:
          claimName: txture-postgres
---
# PostgreSQL Service
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: txture
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432
    name: postgres
---
# Txture Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: txture
  namespace: txture
spec:
  replicas: 1
  selector:
    matchLabels:
      app: txture
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: txture
    spec:
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
        runAsNonRoot: true
      initContainers:
      - name: setup
        image: postgres:15-bullseye
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop: ["ALL"]
        env:
        - name: PGHOST
          value: "${POSTGRES_HOST}"
        - name: PGUSER
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_USER
        - name: PGPASSWORD
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_PASSWORD
        - name: PGDATABASE
          valueFrom:
            secretKeyRef:
              name: txture-db-credentials
              key: POSTGRES_DB
        command: ['/bin/bash', '-c']
        args:
        - |
          echo "=== Txture Init: waiting for data ==="

          echo "Waiting for upload signal (/opt/txture_home/.ready) ..."
          while [ ! -f /opt/txture_home/.ready ]; do
            sleep 10
          done
          echo "Upload signal received."

          echo "Waiting for PostgreSQL at ${PGHOST}:5432 ..."
          until pg_isready -q; do
            echo "  not ready — retrying in 5s ..."
            sleep 5
          done
          echo "PostgreSQL is ready."

          DUMP=$(find /opt/txture_home -maxdepth 1 -name '*_dump.gz' -print -quit)
          if [ -n "$DUMP" ]; then
            echo "Found database dump: $DUMP"
            echo "Restoring database ..."
            gunzip -c "$DUMP" | psql
            echo "Restore complete. Removing dump file from PVC."
            rm "$DUMP"
          else
            echo "No dump file found on PVC, skipping restore."
          fi

          echo "=== Init complete ==="
        volumeMounts:
        - name: txture-home
          mountPath: /opt/txture_home
      containers:
      - name: txture
        image: europe-docker.pkg.dev/txture/production/txture:latest
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop: ["ALL"]
        env:
        - name: CATALINA_OPTS
          value: >-
            -DtxtureHome=/opt/txture_home -XX:MaxRAMPercentage=75.0 -XX:InitialRAMPercentage=75.0 -server
            -Dio.grpc.netty.shaded.io.netty.transport.noNative=true
        - name: TXTURE_DB_JDBC_URL
          value: "jdbc:postgresql://${POSTGRES_HOST}:5432/${POSTGRES_DB}?user=${POSTGRES_USER}&password=${POSTGRES_PASSWORD}"
        ports:
        - containerPort: 8080
          name: http
        volumeMounts:
        - name: txture-home
          mountPath: /opt/txture_home
        resources:
          requests:
            memory: ${TXTURE_MEMORY_REQUEST}
            cpu: ${TXTURE_CPU_REQUEST}
          limits:
            memory: ${TXTURE_MEMORY_LIMIT}
            cpu: ${TXTURE_CPU_LIMIT}
        startupProbe:
          httpGet:
            path: /
            port: 8080
          failureThreshold: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /
            port: 8080
          periodSeconds: 10
        livenessProbe:
          httpGet:
            path: /
            port: 8080
          periodSeconds: 30
      volumes:
      - name: txture-home
        persistentVolumeClaim:
          claimName: txture-home
---
# Txture Service
apiVersion: v1
kind: Service
metadata:
  name: txture
  namespace: txture
spec:
  selector:
    app: txture
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Source the parameter file and apply the manifests using envsubst:

set -a && source txture.env && set +a
envsubst '$POSTGRES_USER $POSTGRES_PASSWORD $POSTGRES_DB $POSTGRES_HOST
  $TXTURE_MEMORY_LIMIT $TXTURE_MEMORY_REQUEST $TXTURE_CPU_REQUEST $TXTURE_CPU_LIMIT
  $TXTURE_STORAGE_SIZE $POSTGRES_STORAGE_SIZE
  $POSTGRES_MEMORY_REQUEST $POSTGRES_MEMORY_LIMIT $POSTGRES_CPU_REQUEST $POSTGRES_CPU_LIMIT' \
  < txture-manifests.yaml | kubectl apply -f -

This creates all resources and starts both PostgreSQL and Txture. The Txture pod's init container will wait for data before the application starts — no manual scaling is needed.

Wait until PostgreSQL is running before continuing:

kubectl get pods -n txture -l app=postgres -w

Ensure the pod shows 1/1 Running before proceeding. The Txture pod will show Init:0/1 — this means the init container is waiting for data, which is the expected state.

The Txture pod's init container is waiting for data. First, get the pod name:

kubectl get pod -n txture -l app=txture -o name

Replace <pod-name> in the commands below with the output (e.g. txture-7b9c8d4e5-xxxxx; you can omit the pod/ prefix).

Copy the contents of your local txture_home directory onto the PVC. Note the trailing /. — this copies the directory contents, not the directory itself:

kubectl cp /path/to/local/txture_home/. <pod-name>:/opt/txture_home/ -c setup -n txture

Signal readiness

Once the copy is complete, signal the init container that the data is ready:

kubectl exec <pod-name> -c setup -n txture -- touch /opt/txture_home/.ready

The init container will then automatically:

1. Wait for PostgreSQL to be ready.
2. Restore the database dump if a *_dump.gz file is found on the PVC (and remove it after a successful restore).
3. Exit, allowing the main Txture container to start.

kubectl logs -n txture -l app=txture -c setup -f

Watch the pod until Txture is running and ready:

kubectl get pods -n txture -l app=txture -w

First startup can take a few minutes after the init container exits. Wait until the pod shows 1/1 Running.

Txture gets the database connection from the TXTURE_DB_JDBC_URL environment variable, which is constructed automatically from the POSTGRES_* parameters in your txture.env file. You typically do not need to configure this manually.

This guide deploys PostgreSQL alongside Txture for convenience, but you can use an external PostgreSQL instance instead. To do so:

1. Remove the PostgreSQL Deployment, Service, and PVC from the manifests (or do not apply them).
2. Set POSTGRES_HOST in your txture.env to the external hostname (e.g. POSTGRES_HOST=db.example.com). This configures both the JDBC connection and the init container's readiness check automatically.

Memory is configured via two parameters in your txture.env file:

• TXTURE_MEMORY_LIMIT: Sets the container memory limit (e.g. 32Gi).
• TXTURE_MEMORY_REQUEST: Sets the memory request, i.e. how much memory the scheduler reserves on the node (e.g. 16Gi).

The JVM heap size is set automatically to 75% of the container memory limit via -XX:MaxRAMPercentage=75.0. You do not need to configure this manually. By default, the memory request is half of the limit, which gives the pod Burstable QoS and avoids over-reserving resources on shared clusters. Set TXTURE_MEMORY_REQUEST equal to TXTURE_MEMORY_LIMIT for Guaranteed QoS on dedicated nodes.

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

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

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

The NodePort service from the installation steps provides basic access but does not offer TLS or hostname-based routing. For production, consider one of the following:

• Ingress with TLS (recommended): Use your cluster's Ingress controller (e.g. NGINX Ingress, Traefik) with a TLS certificate to expose Txture on a proper hostname. This is the standard Kubernetes approach for HTTP services.
• LoadBalancer Service: Change the Service type to LoadBalancer to get an external IP directly. On cloud providers this provisions a cloud load balancer; on bare-metal or edge clusters, tools like MetalLB or k3s ServiceLB provide the same functionality.
• External reverse proxy: Place an nginx or Caddy instance in front of the NodePort or use port forwarding to a local reverse proxy that handles TLS termination. See our example reverse proxy configuration for more details.

Additionally, it is recommended to set up SMTP credentials to enable email functionalities like notifications, user or survey invites.

Further production considerations:

• Use a cluster StorageClass and avoid hostPath.
• Enable volume snapshots for backups where supported.
• Consider separate storage tiers or performance classes for database vs. application data.

• Enable Pod Security Standards (at least baseline, ideally restricted) on the txture namespace.
• The manifests already set allowPrivilegeEscalation: false, capabilities.drop: ["ALL"], and runAsNonRoot: true.
• Consider NetworkPolicies to restrict traffic between namespaces.
• Store database passwords in a secret manager or sealed secrets rather than on the command line.

• Use a multi-node cluster for resilience.
• Use pod anti-affinity so Txture and PostgreSQL pods are spread across nodes.
• For database HA, consider a managed PostgreSQL operator (e.g. CloudNativePG, Crunchy Data) or a cloud-managed database service.

• Back up the PostgreSQL database (e.g. pg_dump or volume snapshots) and the txture_home PVC regularly.
• Test restore procedures in a non-production environment.

Run kubectl get storageclass and ensure a default StorageClass exists and that the provisioner is healthy.

The init container is waiting for data. Check its logs with kubectl logs -n txture -l app=txture -c setup to see what it is waiting for:

• "Waiting for upload signal": The kubectl cp in step 5 has not completed yet, or the signal command (touch .ready) has not been run.
• "Waiting for PostgreSQL": The PostgreSQL pod is not running. Check with kubectl get pods -n txture -l app=postgres.

Ensure txture_home contents (including txture.properties) are at the root of the volume, not inside an extra subdirectory, and that the Txture deployment mounts the same PVC at /opt/txture_home.

If the Txture pod crashes with The main resource set specified [/usr/local/tomcat/webapps/txture] is not a directory or war file, the container is running with the wrong UID. Ensure the pod security context sets runAsUser: 1000 and fsGroup: 1000.

Confirm PostgreSQL is running: kubectl get pods -n txture -l app=postgres. Check that the TXTURE_DB_JDBC_URL environment variable is correct: kubectl exec -n txture deployment/txture -- env | grep JDBC It should match the PostgreSQL service (postgres:5432) and the credentials in your txture.env.

Install gettext on your system:

• macOS: brew install gettext
• Ubuntu/Debian: sudo apt install gettext-base
• Fedora/RHEL: sudo dnf install gettext