Installation (Kubernetes)

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

  • Kubernetes cluster v1.18.14 - v1.20.2
  • kubectl, the Kubernetes CLI
  • Helm v3, the Kubernetes package manager

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

The installation instructions go through the following steps:

  1. Install ingress-nginx
  2. Install cert-manager (optional)
  3. Install xltrail
  4. Login
  5. Advanced Configuration

1. 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 install ingress-nginx 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.

2. Install cert-manager

This step is optional but highly recommended to secure access to xltrail via TLS certificates, i.e., enable https. See also the cert-manager docs. Install cert-manager by running the following:

kubectl create namespace cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm 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.

3. Install xltrail

3.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 3.2 and 3.3.

3.2 Secrets

Run the following commands to create the required secrets.

  • Docker Registry (details will be provided by email)

    kubectl create secret docker-registry xltrail-registry-credentials --docker-server=registry.gitlab.com --docker-username=<USERNAME> --docker-password=<PASSWORD>
    
  • License Key (details be 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_CTYPE=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_CTYPE=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_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
    
  • 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>
    

You should back up the generated secrets so you can move them to a new cluster if you have to.

3.3 xltrail

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 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.

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

4. 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.

5. Advanced Configuration

For a more detailed configuration of your installation, have a look at the Helm chart's values.yaml file:

global:
  registryCredentialsSecretName: xltrail-registry-credentials
  # If no storageClassName is provided, it uses the default storageClassName of your
  # Kubernetes provider as provided by: kubectl get storageclass
  storageClassName:

xltrail:
  licenseKeySecretName: xltrail-license-key
  secretKeySecretName: xltrail-secret-key

  # If you rely on CA Certificates to connect with your Git or LDAP provider, upload
  # them like this:
  # kubectl create secret generic xltrail-ca-certificates --from-file=<cert1>.crt --from-file=<cert2>.crt
  # Note that the extension must be ".crt". Then uncomment the next line:
  # caCertificatesSecretName: xltrail-ca-certificates

  # During startup, containers check every 5 seconds if the database is up and
  # running. Increase number of retries if the db-migration Job fails
  # dbCheckRetries: 60

  # This is only relevant if you use the Git integration. If your Git repos sync
  # correctly when disabled (0), disable it for increased security, otherwise
  # leave it at 1. Sometimes 1 is required, e.g. if you’re using a self-signed
  # certificate to serve Git repositories over HTTPS
  # gitSslNoVerify: 1

  # LDAP settings, see:
  # https://www.xltrail.com/docs/en/stable/configuration#active-directory--ldap
  # authProvider: ldap
  # ldapUrl: 
  # ldapBindDn: 
  # ldapBindPasswordSecretName: xltrail-ldap-bind-password
  # ldapBaseDn: 
  # ldapUserDn: 
  # ldapUserEmailAttribute: mail
  # ldapUserDisplaynameAttribute: cn
  # ldapUserFilter: 
  # ldapAdminFilter: 

git:
  remoteRepos:
    # Remotes of the drag-and-drop projects
    storageSize: 10Gi
    storageClassName:
  clonedRepos:
    # Used for both the drag-and-drop projects and Git integrations
    storageSize: 50Gi
    storageClassName:

frontend:
  imageRegistry: registry.gitlab.com
  imageRepository: xltrail/xltrail/nginx

server:
  imageRegistry: registry.gitlab.com
  imageRepository: xltrail/xltrail/server

redis:
  imageRegistry: registry.gitlab.com
  imageRepository: xltrail/xltrail/redis

minio:
  # Minio is an object storage used for diff caching and inter-container communication
  imageRegistry: docker.io
  imageRepository: minio/minio
  imageTag: RELEASE.2021-03-12T00-00-47Z
  storageSize: 10Gi
  storageClassName:
  accessKey: xltrail
  secretKeySecretName: xltrail-minio-secret-key

postgresql:
  external: false
  passwordSecretName: xltrail-postgresql-password
  imageRegistry: docker.io
  imageRepository: postgres
  imageTag: 13.2-alpine
  # The following 2 lines are used with an internal database via "external: false"
  storageSize: 10Gi
  storageClassName:
  # The following lines are required when using an external database via "external: true"
  # host:
  # port:
  # database:
  # username:

ingress:
  # Ingress rules, requires an existing installation of ingress-nginx
  enabled: true
  host:
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: xltrail-cert-issuer
  tls:
    # Requires an existing installation of cert-manager with a certificate issuer that
    # matches the above annotation 
    enabled: false
    secret: xltrail-tls

results matching ""

    No results matching ""