What is Tolgee?

Tolgee is a localization tool created to make several aspects around translations easier. The management process of creating, managing, and fixing localization strings is complicated and usually involves developers more than it should.

Why Kubernetes?

I currently have a lot of client projects hosted in Kubernetes. The Tolgee documentation does not contain any information on how to deploy their solution to Kubernetes, so I decided to make my own guide on it.

How to

Requirements

Some kind of Kubernetes platform, I personally used minikube to create this guide
Basic knowledge of Kubernetes related terms such Service, Deployment, PersistentVolume, PersistentVolumeClaim.
Some of your time to read this guide 🧾 and try it out yourself.

Set up your Kubernetes cluster

This part will vary based on the Kubernetes solution / provider you are using. I will be using minikube examples going forward.

Start up minikube using

minikube start

Which should result in something like this:

😄  minikube v1.26.1 on Microsoft Windows 10 Pro 10.0.19043 Build 19043
✨  Using the docker driver based on existing profile
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔄  Restarting existing docker container for "minikube" ...
🐳  Preparing Kubernetes v1.24.3 on Docker 20.10.17 ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
💡  After the addon is enabled, please run "minikube tunnel" and your ingress resources would be available at "127.0.0.1"
    ▪ Using image gcr.io/k8s-minikube/minikube-ingress-dns:0.0.2
🌟  Enabled addons: ingress-dns
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Required Kubernetes Resources

We will be needing a few Kubernetes resources.

A Deployment which deploys our Tolgee application
A Service which exposes our Tolgee Application
A PersistentVolume to store our data on
A PersistentVolumeClaim so that our containers in the pods of our deployment can access our data

Creating the resources

We will be creating a .yaml file for each resource that allows us to easily deploy (apply) our resources onto our cluster. After creating these files, we will deploy them to our Kubernetes cluster in the next step.

The PersistentVolume

The Tolgee docker container runs an embedded PostgreSQL instance. This means that if we do not want to lose our data after a container restart, we have the need to save our data outside our container. This is where the PersistentVolume and PersistentVolumeClaim come in.

apiVersion: v1
kind: PersistentVolume # Create PV
metadata:
  name: tolgee-volume # Sets PV name
  labels:
    type: local # Sets PV's type
    app: tolgee
spec:
  storageClassName: standard # This highly depends on your Kubernetes solution, be sure to check the documentation
  capacity:
    storage: 10Gi # Sets PV's size
  accessModes:
    - ReadWriteMany
  hostPath:
    path: '/data' # Sets PV's host path, this might be overkill for some translations though

The PersistentVolumeClaim

apiVersion: v1
kind: PersistentVolumeClaim # Create PVC
metadata:
  name: tolgee-volume-claim # Sets PVC's name
  labels:
    app: tolgee # Defines app to create PVC for
spec:
  storageClassName: standard # This highly depends on your Kubernetes solution, be sure to check the documentation
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi # Sets PVC's size, this might be overkill for some translations though

The Deployment

apiVersion: apps/v1
kind: Deployment # Create a deployment
metadata:
  name: tolgee # Set the name of the deployment
spec:
  replicas: 1 # Set 1 deployment replica
  selector:
    matchLabels:
      app: tolgee
  template:
    metadata:
      labels:
        app: tolgee
    spec:
      containers:
        - name: tolgee
          image: tolgee/tolgee
          imagePullPolicy: 'IfNotPresent'
          env:
            # This enables user authentication in Tolgee. Without this environment, there is only a default account with credentials, which is not suited when you want to let your stakeholders manage translations.
            - name: TOLGEE_AUTHENTICATION_ENABLED
              value: 'true'
          ports:
            - containerPort: 8080 # Expose the web app
              name: web-app
              # You could expose the PostgreSQL port if you'd want to, but this will entail a security risk as the PostgreSQL has default credentials.
            # - containerPort: 5432
            #   name: postgres
          volumeMounts:
            - mountPath: /data
              name: tolgeedata
          resources:
            requests:
              memory: '1024Mi'
              cpu: '500m'
            limits:
              memory: '1024Mi'
              cpu: '1000m'

      volumes:
        - name: tolgeedata
          persistentVolumeClaim:
            claimName: tolgee-volume-claim # Refer to the previously made PersistentVolumeClaim

The Service

To expose the web application, we want a Service, which can then be referred to from an Ingress later on.

apiVersion: v1
kind: Service
metadata:
  name: tolgee
spec:
  selector:
    app: tolgee
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080

Deploying everything

We created all the resources in .yaml files. It is now time to deploy them.

kubectl apply -f tolgee-volume.yaml
kubectl apply -f tolgee-volume-claim.yaml
kubectl apply -f tolgee-deployment.yaml
kubectl apply -f tolgee-service.yaml

After executing the commands above, wait a few minutes as the Tolgee container in the pod will be doing some first time setup such as seeding its database scheme.
If you are a curious and/or impatient person like me, you can use the following commands to find out what Tolgee is doing:
- kubectl get pods | grep tolgee to get the exact Pod name you deployed.
- kubectl logs tolgee-86897bb8f7-8x5cr to see the logs in the Pod.

What now?

After the pod has been deployed and has booted up successfully, it is time to use the application.
If you have an existing Ingress controller set up, you could create an Ingress such as below:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tolgee-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - http:
        paths:
          - path: /tolgee
            pathType: Prefix
            backend:
              service:
                name: tolgee
                port:
                  number: 8080

If you do not have an Ingress, and want to try out your application quickly, the easiest way will be to port forward using the following: kubectl port-forward service/tolgee 8080:8080
- After doing this, you should be able to access the web application at http://localhost:8080.
The credentials for the default admin user are randomly generated at startup, so there will be some steps left to do here before we can start using the application.
- The default username is admin.
- The default password needs to be found in the container itself, as Tolgee saves the initial password in a file inside the container.
  - You can get the password by running the following commands:
    - SSH into the container: kubectl exec --stdin --tty tolgee-86897bb8f7-8x5cr -- /bin/bash
    - To print the password cat /data/initial.pwd ; echo
- Log into the web application with your freshly acquired password.
- Do not forget to change this password as you never want to use an initially generated password for security reasons.

Conclusion

A few simple Kubernetes resources later, we successfully deployed our Tolgee application to Kubernetes. I hope this helps people who want to use this awesome tool in Kubernetes.

Is there a part of this guide that was not obvious or extensive enough? Let me know on Twitter.

Deploying Tolgee to Kubernetes