Installation (Kubernetes)

1. Requirements

xltrail can be installed on a Kubernetes cluster via Helm chart. You'll need the following prerequisites:

• Kubernetes cluster (tested versions: 1.18.14 - 1.29.1)
• kubectl, the Kubernetes CLI
• Helm, the Kubernetes package manager (v3)

You can start with a single node, but it is recommended to use one with at least 4 CPU cores and 4GB RAM, such as Standard_D4s_v3 on Azure.

2. Install ingress-nginx

The ingress is required to make xltrail accessible from outside your cluster. xltrail expects the community-managed ingress-nginx. Install it by running the following:

kubectl create namespace ingress-nginx
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install ingress-nginx --set controller.allowSnippetAnnotations=true ingress-nginx/ingress-nginx --namespace ingress-nginx

This will provision a managed Load Balancer and might take a minute or two. Once ready, you can get the external IP of your Load Balancer via:

kubectl get services/ingress-nginx-controller -n ingress-nginx

In your DNS configuration, create an A record (e.g., xltrail.mycompany.com) that points to this IP. Depending on your provider, you may also want to configure a static IP that resolves to the Load Balancer's IP and point your A record to this IP instead. For Azure, see: https://docs.microsoft.com/en-us/azure/aks/static-ip.

Internal LoadBalancer

If you want to expose your ingress to an internal network, you will have to configure your Helm chart accordingly. For example, on Azure, you need to create a file internal-ingress.yaml with the following content:

# internal-ingress.yaml
controller:
  service:
    loadBalancerIP: 10.240.0.42  # TODO: Change to your internal IP
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "true"
      service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "your-subnet"

Then run the following installation command instead:

helm upgrade --install ingress-nginx --set controller.allowSnippetAnnotations=true ingress-nginx/ingress-nginx --namespace ingress-nginx -f internal-ingress.yaml

For more details, see: https://docs.microsoft.com/en-us/azure/aks/ingress-internal-ip

3. Install cert-manager

This step is only required if you want to secure access to xltrail via TLS certificates that need to be renewed automatically on a regular basis, like for example those from Let's Encrypt. If your certificates are delivered by an internal team, we'll see in the next section how you can upload them as secrets to your cluster.

If you want to use TLS certs that can be renewed by cert-manager, install it like so, see also the cert-manager docs:

kubectl create namespace cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager --set installCRDs=true --namespace cert-manager

After installing cert-manager, you'll need to create a certificate issuer. Create a file called cert-issuer.yaml with the following content (make sure to fill in your email address).

This example shows how to configure a certificate of type ACME with Let's Encrypt as the certificate authority, but you can use a different configuration according to your needs by following the cert-manager's docs under Configuration.

# cert-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: xltrail-cert-issuer
  namespace: cert-manager
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: YOUR@EMAIL
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: xltrail-acme-private-key
    # Enable the HTTP-01 challenge provider
    solvers:
      - http01:
          ingress:
            class: nginx

Then, run the following command to create the certificate issuer:

kubectl apply -f cert-issuer.yaml

At this point you haven't issued any certificates yet, they will be issued when you install xltrail with the option --set ingress.tls.enabled=true, as we'll see below.

4. Install xltrail

4.1 Namespace

Start by creating a namespace for xltrail. We'll be using xltrail throughout these instructions, but you may want to call it differently, e.g., xltrail-prod etc.

kubectl create namespace xltrail

Since the remaining commands will have to be run in this namespace, the easiest way is to set your current context to this namespace:

kubectl config set-context --current --namespace=xltrail

Confirm that the namespace has been correctly set:

kubectl config view --minify | grep namespace:

Instead of changing the current context, you could also add the --namespace=xltrail argument to the commands under 4.2 and 4.3.

4.2 Secrets

Run the following commands to create the required secrets.

• Docker Registry (make sure to replace both <USERNAME> and <PASSWORD> with the actual values provided by email)

  kubectl create secret docker-registry xltrail-registry-credentials --docker-server=registry.gitlab.com --docker-username=<USERNAME> --docker-password=<PASSWORD>
  

• License Key (make sure to replace <LICENSE_KEY> with the actual license key provided by email)

  kubectl create secret generic xltrail-license-key --from-literal=LICENSE_KEY=<LICENSE_KEY>
  

• Secret Key

  kubectl create secret generic xltrail-secret-key --from-literal=SECRET_KEY=$(head -c 512 /dev/urandom | LC_ALL=C tr -cd 'a-zA-Z0-9' | head -c 64)
  

• Postgres

  kubectl create secret generic xltrail-postgresql-password --from-literal=POSTGRES_PASSWORD=$(head -c 512 /dev/urandom | LC_ALL=C tr -cd 'a-zA-Z0-9' | head -c 64)
  

  In case you're using an externally hosted PostgreSQL instance, provide the password instead of generating a random one.

• Minio

  kubectl create secret generic xltrail-minio-secret-key --from-literal=MINIO_SECRET_KEY=$(head -c 512 /dev/urandom | LC_ALL=C tr -cd 'a-zA-Z0-9' | head -c 64)
  

• TLS certificates (optional)
  Only upload TLS certificates that you manage manually. If you use cert-manager or want to access xltrail via http rather than https, this is not required. See also: https://kubernetes.github.io/ingress-nginx/user-guide/tls/

  kubectl create secret tls xltrail-tls --key <YOUR-INGRESS-TLS.key> --cert <YOUR-INGRESS-TLS.crt>
  

• LDAP (optional)
  If you intend to use LDAP for authentication, set the Bind Password here.

  kubectl create secret generic xltrail-ldap-bind-password --from-literal=LDAP_BIND_PASSWORD=<PASSWORD>
  

• SMTP Password (optional)
  If you intend to use an SMTP server to send password reset emails, set the SMTP Password here.

  kubectl create secret generic xltrail-smtp-password --from-literal=SMTP_PASSWORD=<PASSWORD>
  

You should back up the generated secrets, so you can move them to a new cluster if you have to. For example, if you want to retrieve the password of the Postgres user, you could do:

  kubectl get secret xltrail-postgresql-password -ojsonpath='{.data.POSTGRES_PASSWORD}' | base64 --decode ; echo

4.3 xltrail application

With nginx-ingress and cert-manager installed and the secrets created, you can now install xltrail with the following commands:

helm repo add xltrail https://xltrail.com/charts
helm repo update
helm upgrade --install xltrail xltrail/xltrail --set ingress.host=<HOST> --set ingress.tls.enabled=true

Set <HOST> to the domain you configured under point 1, e.g., xltrail.mycompany.com. If you skipped point 2 (cert-manager), you will need to disable TLS via --set ingress.tls.enabled=false. For advanced configuration, see "6. Advanced Configuration via values.yaml" below.

Note that the installation will take a couple of minutes. Confirm that all pods show their status as Running by running the following command:

kubectl get pods

At this point, consider resetting your current context again via:

kubectl config set-context --current --namespace=default

5. Login

With all pods running, type your domain name (e.g., xltrail.mycompany.com) into a web browser and login with both username and password admin.

• Once you are logged in, you can add new projects and/or Git integrations, see here.
• You can add users manually by going to the user icon on the top right, then Settings > Team. If you would rather want to connect xltrail with your LDAP/AD directory, have a look at the LDAP docs.

Change the admin's password in the app via the user icon on the top right, then selecting Change Password.

6. Advanced Configuration via values.yaml

For a more detailed configuration of your installation, instead of using --set statements as we did above, you can adjust the configuration via the Helm chart's values.yaml file. Start by exporting the file like this:

helm show values xltrail/xltrail > values.yaml

After changing the values, you can install/upgrade the helm chart as follows:

helm upgrade --install xltrail xltrail/xltrail -f values.yaml

7. Troubleshooting

a) Accessing the logs

To access the logs, run the following commands:

kubectl logs service/xt-web --all-containers=true
kubectl logs -l app=xt-excel-parser
kubectl logs -l app=xt-runner
kubectl logs -l app=xt-differ-sequencematch
kubectl logs -l app=xt-differ-rowcolalign

To limit the amount of logs, add --tail. For example, to limit to the most recent 20 lines:

kubectl logs --tail=20 -l app=xt-excel-parser

To live tail/stream the logs, use the -f argument, for example:

kubectl logs -f -l app=xt-excel-parser

Our support can indicate which logs are of primary concern depending on the issue you're seeing.

b) Debugging ingress issues

If you can't access xltrail, try to access xltrail directly via port-forwarding (you'll need to do this from a local Terminal, not a cloud shell):

kubectl port-forward svc/xt-frontend 8080:80 -n xltrail

This should print the following:

Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

Then go to http://127.0.0.1:8080 in your browser and see if the xltrail login screen appears. If it does, you either have a misconfiguration in your ingress-nginx, cert-manager or in the ingress configuration of your xltrail Helm chart.

c) Updating the LICENSE_KEY

1. Delete the existing secret:

   kubectl delete secret xltrail-license-key
   

2. Recreate the secret like this (replace MYLICENSEKEY with your own license key):

   kubectl create secret generic xltrail-license-key --from-literal=LICENSE_KEY=MYLICENSEKEY
   

3. Restart the pods by running the helm upgrade command:

   helm upgrade xltrail xltrail/xltrail -f myvalues.yaml
   

8. Useful Kubernetes Commands

Show installed xltrail version

$ helm list --namespace xltrail
NAME       NAMESPACE    REVISION    UPDATED                                  STATUS      CHART            APP VERSION
xltrail    xltrail      7           2021-10-28 16:50:32.191718 +0200 CEST    deployed    xltrail-1.0.9    3.4.9

Make sure to replace xltrail with the name of the namespace where xltrail is installed.

Show available xltrail versions

$ helm search repo xltrail/xltrail --versions
NAME               CHART VERSION    APP VERSION    DESCRIPTION                             
xltrail/xltrail    1.0.9            3.4.9          A version control system for Excel files
xltrail/xltrail    1.0.8            3.4.8          A version control system for Excel files
xltrail/xltrail    1.0.7            3.4.8          A version control system for Excel files
...

Install a specific version of xltrail

$ helm upgrade xltrail xltrail/xltrail --version 1.0.8

As usual, replace upgrade with install if the Chart is not installed yet and include all the arguments from your original installation such as -f myvalues.yaml. Note that the version refers to the Chart version, not the app version!