Installation: Kubernetes

This guide runs GoEasyERP on a Kubernetes cluster. It uses the same images as the other installations: a PostgreSQL database, the backend and the frontend, each as a Deployment with a Service, plus an Ingress that makes it available under your own address. For a single computer or server without Kubernetes see Windows or Linux and macOS.

You need:

  • a cluster and kubectl access to it,
  • an ingress controller and a default StorageClass (or set storageClassName on the volume claims),
  • a hostname for GoEasyERP, written below as erp.example.com, and a TLS certificate for it.

1. Namespace and secret

The database password and the key that signs sessions go into a Secret, not into the manifests:

kubectl create namespace goeasyerp
kubectl -n goeasyerp create secret generic goeasyerp-secret \
  --from-literal=db-password="$(openssl rand -hex 24)" \
  --from-literal=jwt-secret="$(openssl rand -hex 32)"

If you keep your cluster configuration in git, encrypt the Secret first with a tool such as SOPS or Sealed Secrets. Never commit it as plain text.

2. Manifests

Create a folder called goeasyerp and save each of the boxes below in it as a file with the name shown above the box. Before you apply them:

  • Replace both VERSION placeholders with the release you want to run, the same one for the backend and the frontend. The versions are listed on the releases page.
  • Replace erp.example.com with your hostname. In the frontend, ORIGIN must be the exact public address, including https://.
  • Set ingressClassName and the certificate in the Ingress to match your cluster.

PersistentVolumeClaim

The storage for the database.

postgres-volume.yaml – storage for the database

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: goeasyerp-postgres
  namespace: goeasyerp
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 10Gi

Deployments

The database, the backend and the frontend. The database uses strategy: Recreate on purpose: with the default rolling update, the old and the new pod could run on the same data directory at once, which can corrupt the database.

postgres-deployment.yaml – the database

apiVersion: apps/v1
kind: Deployment
metadata:
  name: goeasyerp-postgres
  namespace: goeasyerp
spec:
  replicas: 1
  strategy:
    type: Recreate          # never two Postgres servers on one data directory
  selector:
    matchLabels: {app: goeasyerp-postgres}
  template:
    metadata:
      labels: {app: goeasyerp-postgres}
    spec:
      containers:
        - name: postgres
          image: postgres:16
          ports:
            - containerPort: 5432
          env:
            - {name: POSTGRES_USER, value: openerp}
            - {name: POSTGRES_DB, value: openerp}
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef: {name: goeasyerp-secret, key: db-password}
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
              subPath: data
          securityContext:
            allowPrivilegeEscalation: false
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: goeasyerp-postgres

backend-deployment.yaml – the backend

apiVersion: apps/v1
kind: Deployment
metadata:
  name: goeasyerp-backend
  namespace: goeasyerp
spec:
  replicas: 1
  selector:
    matchLabels: {app: goeasyerp-backend}
  template:
    metadata:
      labels: {app: goeasyerp-backend}
    spec:
      containers:
        - name: backend
          image: ghcr.io/hansjlachmann/goeasyerp/backend:VERSION
          ports:
            - containerPort: 8080
          env:
            - {name: PORT, value: "8080"}
            - {name: DB_HOST, value: goeasyerp-postgres}
            - {name: DB_PORT, value: "5432"}
            - {name: DB_USER, value: openerp}
            - {name: DB_NAME, value: openerp}
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef: {name: goeasyerp-secret, key: db-password}
            - name: JWT_SECRET
              valueFrom:
                secretKeyRef: {name: goeasyerp-secret, key: jwt-secret}
          securityContext:
            allowPrivilegeEscalation: false

frontend-deployment.yaml – the frontend

apiVersion: apps/v1
kind: Deployment
metadata:
  name: goeasyerp-frontend
  namespace: goeasyerp
spec:
  replicas: 1
  selector:
    matchLabels: {app: goeasyerp-frontend}
  template:
    metadata:
      labels: {app: goeasyerp-frontend}
    spec:
      containers:
        - name: frontend
          image: ghcr.io/hansjlachmann/goeasyerp/frontend:VERSION
          ports:
            - containerPort: 3000
          env:
            - {name: PORT, value: "3000"}
            - {name: ORIGIN, value: "https://erp.example.com"}    # the public address
            - {name: BACKEND_URL, value: "http://goeasyerp-backend:8080"}
          securityContext:
            allowPrivilegeEscalation: false

Services

One Service for each Deployment, so the pods can reach each other by name.

postgres-service.yaml – the database

apiVersion: v1
kind: Service
metadata: {name: goeasyerp-postgres, namespace: goeasyerp}
spec:
  selector: {app: goeasyerp-postgres}
  ports: [{port: 5432}]

backend-service.yaml – the backend

apiVersion: v1
kind: Service
metadata: {name: goeasyerp-backend, namespace: goeasyerp}
spec:
  selector: {app: goeasyerp-backend}
  ports: [{port: 8080}]

frontend-service.yaml – the frontend

apiVersion: v1
kind: Service
metadata: {name: goeasyerp-frontend, namespace: goeasyerp}
spec:
  selector: {app: goeasyerp-frontend}
  ports: [{port: 3000}]

Ingress

Makes GoEasyERP available at your hostname: the frontend at / and the backend at /api.

ingress.yaml – the Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: goeasyerp
  namespace: goeasyerp
spec:
  # ingressClassName: nginx            # set the class of your ingress controller
  tls:
    - hosts: [erp.example.com]
      secretName: goeasyerp-tls        # your certificate, or let cert-manager create it
  rules:
    - host: erp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: {name: goeasyerp-frontend, port: {number: 3000}}
          - path: /api
            pathType: Prefix
            backend:
              service: {name: goeasyerp-backend, port: {number: 8080}}

3. Start it

kubectl apply -f goeasyerp/
kubectl -n goeasyerp get pods
kubectl -n goeasyerp logs deploy/goeasyerp-backend

When all three pods are Running, open https://erp.example.com and create the first user. Database migrations run automatically when the backend starts. They take a lock, so backend pods starting at the same time are safe.

Do not delete the goeasyerp-postgres volume claim. It holds the database.

To use a database outside the cluster instead, leave out the PostgreSQL Deployment, Service and volume claim, and point the backend’s DB_HOST, DB_PORT, DB_USER and DB_NAME at it.

Upgrading

  1. Take a backup (see below).
  2. Change the image version in backend-deployment.yaml and frontend-deployment.yaml to the new release and run kubectl apply -f goeasyerp/.
  3. Watch the backend log for migration messages and errors: kubectl -n goeasyerp logs deploy/goeasyerp-backend.

To roll back, set the previous version and apply again. If a migration changed data in a way the old version cannot read, restore the backup you took before upgrading.

Backups

This CronJob dumps the database every night at 02:15 into its own volume and keeps 14 days. Save it as goeasyerp-backup.yaml and apply it:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: goeasyerp-backup
  namespace: goeasyerp
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 5Gi
---
apiVersion: batch/v1
kind: CronJob
metadata:
  name: goeasyerp-backup
  namespace: goeasyerp
spec:
  schedule: "15 2 * * *"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: pg-dump
              image: postgres:16
              env:
                - name: PGPASSWORD
                  valueFrom:
                    secretKeyRef: {name: goeasyerp-secret, key: db-password}
              command:
                - /bin/sh
                - -c
                - |
                  set -eu
                  file="/backup/goeasyerp-auto-$(date +%Y%m%d-%H%M).dump"
                  pg_dump -h goeasyerp-postgres -U openerp -d openerp -Fc -f "$file.partial"
                  test -s "$file.partial"
                  mv "$file.partial" "$file"
                  find /backup -maxdepth 1 -name 'goeasyerp-auto-*.dump' -mtime +14 -delete
              volumeMounts:
                - {name: backup, mountPath: /backup}
          volumes:
            - name: backup
              persistentVolumeClaim:
                claimName: goeasyerp-backup

Take a backup right now with:

kubectl -n goeasyerp create job --from=cronjob/goeasyerp-backup goeasyerp-backup-manual

These dumps live in the same cluster as the database. They protect against mistakes such as deleted data or a bad migration, but not against losing the cluster’s storage, so copy them off the cluster as well.

Restore

Restoring replaces the data of the running database. Start a temporary pod that mounts the backup volume, stop the backend, restore and start the backend again:

kubectl -n goeasyerp run backup-shell --image=postgres:16 --restart=Never --overrides='{"spec":{"containers":[{"name":"backup-shell","image":"postgres:16","command":["sleep","3600"],"volumeMounts":[{"name":"b","mountPath":"/backup"}]}],"volumes":[{"name":"b","persistentVolumeClaim":{"claimName":"goeasyerp-backup"}}]}}'
kubectl -n goeasyerp exec backup-shell -- ls -lh /backup
kubectl -n goeasyerp scale deploy/goeasyerp-backend --replicas=0
kubectl -n goeasyerp exec -it backup-shell -- pg_restore -h goeasyerp-postgres -U openerp -d openerp --clean --if-exists --no-owner /backup/<file>.dump
kubectl -n goeasyerp scale deploy/goeasyerp-backend --replicas=1
kubectl -n goeasyerp delete pod backup-shell

pg_restore asks for the database password: it is the db-password value of the goeasyerp-secret Secret. Other tasks, such as changing the database password or the JWT secret, are described in the operations guide on GitHub for the Docker installation; the same ideas apply, using the Secret.