WProofreader GitOps examples

The badges show the chart versions in main. We test each change of these versions with Argo CD and Flux before it goes to main.

This repository contains example configurations that deploy the WProofreader stack on Kubernetes with a GitOps controller. The stack has WProofreader Server, Admin-panel, and a MySQL database. You keep the configuration in Git, and the controller installs the stack and keeps the cluster equal to Git.

The Helm charts install the components of the stack. A complete deployment also needs settings that connect the components and start them in the correct order. For example, MySQL must be ready before the database Jobs run, all components must use the same Secret names and passwords, and the public route must send WProofreader requests to WProofreader Server.

This repository provides that integration as a version-pinned reference configuration. It also shows how Argo CD and Flux can keep the installed resources equal to the configuration in Git. Copy the example and change it for your cluster. If your team does not use a GitOps controller, use the Kubernetes installation guide and install the same charts with Helm commands.

WProofreader supports three ways to deploy the stack:

Use this repository if your team operates Kubernetes with Argo CD or Flux, or if you want these results:

• All settings (chart versions, values, host names) are in Git. Each change is a commit that people can review, and you can revert it.
• The controller installs the components in the correct order: the cluster components, then MySQL, WProofreader Server, and Admin-panel.
• The controller corrects manual changes in the cluster.
• You add an environment, for example staging or production, with one new directory of values files.

The configurations use the same charts, namespace (wsc), release names, Secret names, and Secret keys as the Kubernetes installation guide. Read that guide to learn what each component does and how the components connect.

The repository has one complete configuration for each controller. Use the controller that your team already operates:

Use only one directory. Each directory deploys the full stack from one root file and does not refer to the other directory.

1. Try the example on a local test cluster. Follow the "Step by step" section in the README of your controller. This deploys the demo environment from this repository without changes.
2. Make your own copy of the repository, and change the settings for your installation. See Make your own copy.
3. Create the Secrets in your cluster. See Secrets.
4. Apply the root file from your copy. The controller then deploys the stack.
5. Make all later changes in Git: values, chart versions, and environments. Do not use helm upgrade or kubectl edit on the components. The controller replaces such changes.

Each controller directory contains:

• A root file that you apply one time. The controller then deploys all other parts from Git.
• The shared cluster components: Gateway API CRDs, cert-manager, a self-signed ClusterIssuer, and Traefik as the Gateway API controller.
• One directory for each environment, with plain Helm values files for MySQL, WProofreader Server, and Admin-panel. You can also use these files with helm install --values.
• Pinned revisions of the product charts.
• Instructions to add an environment, change a chart version, and remove the stack.

The product charts are in their own repositories: wproofreader-helm, admin-panel-helm, and mysql-server-helm. This repository refers to them by URL and pinned revision.

• Argo CD 3.5 or Flux 2.9.
• Kubernetes 1.31 or later with Argo CD, and 1.33 or later with Flux 2.9. The Gateway API v1.6.1 CRDs do not install on versions before 1.31, and Flux 2.9 does not support versions before 1.33.
• A LoadBalancer implementation for the Traefik Service. Without an external address, you cannot reach the stack from outside the cluster, and Argo CD does not report Traefik as healthy.
• A WProofreader license ticket ID.

The product charts are pinned to release tags. See Pinned versions.

Both controllers install the shared components first. Then, for each environment, they install MySQL, WProofreader Server, and Admin-panel in this order. Before WProofreader Server starts, a db-manager hook Job creates the cloud_service database and its users. Before Admin-panel starts, a migration hook Job creates the tables in admin_panel_db.

The demo environment uses the wsc namespace and the host name wproofreader.example.com. Admin-panel and the WProofreader Server API use the same host name:

• https://wproofreader.example.com/ opens Admin-panel.
• https://wproofreader.example.com/wscservice/api goes to WProofreader Server.

The repository does not contain secret values. Each chart reads its credentials from an existing Secret. Create these Secrets in the namespace of the environment before the first sync. For production, create them with your secret-management system, for example Sealed Secrets, SOPS, or External Secrets.

Three passwords occur in two Secrets each. Use the same value in both:

For a test cluster, you can create the Secrets with kubectl:

export WPR_LICENSE_TICKET_ID='<license_ticket_id>'
export MYSQL_ADMIN_PASSWORD="$(openssl rand -hex 16)"
export ADMIN_PANEL_DB_PASSWORD="$(openssl rand -hex 16)"
export APPSERVER_DB_PASSWORD="$(openssl rand -hex 16)"
export SERVICE_DB_PASSWORD="$(openssl rand -hex 16)"
export APP_KEY="base64:$(openssl rand -base64 32)"

kubectl create namespace wsc
kubectl -n wsc create secret generic mysql-credentials \
  --from-literal=mysql-root-password="${MYSQL_ADMIN_PASSWORD}" \
  --from-literal=mysql-password="${ADMIN_PANEL_DB_PASSWORD}"
kubectl -n wsc create secret generic wproofreader-db \
  --from-literal=root-password="${MYSQL_ADMIN_PASSWORD}" \
  --from-literal=appserver-password="${APPSERVER_DB_PASSWORD}" \
  --from-literal=admin-panel-password="${SERVICE_DB_PASSWORD}"
kubectl -n wsc create secret generic wproofreader-license \
  --from-literal=license="${WPR_LICENSE_TICKET_ID}"
kubectl -n wsc create secret generic admin-panel-secrets \
  --from-literal=APP_KEY="${APP_KEY}" \
  --from-literal=DB_PASSWORD="${ADMIN_PANEL_DB_PASSWORD}" \
  --from-literal=SERVICE_DB_PASSWORD="${SERVICE_DB_PASSWORD}"

Keep the values in your password manager. Do not change APP_KEY after the first install: Admin-panel cannot read its encrypted data with a different key.

The controller reads the configuration from a Git repository. To change any setting, you need a copy of this repository on a Git server that your cluster can read, for example a fork or a new private repository.

1. Copy the repository to your Git server.

2. Change the repository URL https://github.com/WebSpellChecker/wproofreader-gitops to the URL of your copy. To find all files that contain it, run:

   grep -rl 'WebSpellChecker/wproofreader-gitops' argocd flux

   In argocd/, the URL is in the root files, bootstrap/, shared/apps/, and wproofreader-stack/values.yaml. In flux/, it is in root.yaml only.

3. If your copy uses a branch other than main, change the branch in the same files (targetRevision and revision for Argo CD, branch for Flux).

4. Change the values files of your environment. At a minimum, change the host name and the certificate issuer. See Production notes.

5. If your copy is private, give the controller read access. See step 3 in the README of your controller.

The product charts are pinned to release tags. The tags are in argocd/wproofreader-stack/values.yaml and flux/sources/charts.yaml. The Argo CD and Flux pins must stay equal. scripts/check-parity.sh compares the tags and the chart directories of the two directories.

The versions in the READMEs are the minimum chart versions for these configurations. After each chart release, we change the tags in both directories. Before the change goes to main, we deploy both directories on a test cluster and check the stack. To find the chart versions, see the releases of wproofreader-helm, admin-panel-helm, and mysql-server-helm. The appVersion in the Chart.yaml file of a chart is the application version that the chart installs.

The cert-manager and Traefik chart versions and the Gateway API version are in the shared configuration of each directory. Change a version deliberately, and test the change before you use it in production. Change the Gateway API version and the Traefik chart version together.

Traefik is the default Gateway API controller. To use another controller, for example Envoy Gateway:

1. Replace the Traefik Application (argocd/shared/apps/02-traefik.yaml) or the Traefik HelmRelease (flux/shared/traefik/) with the other controller.
2. In the admin-panel.yaml values file of each environment, set gateway.gatewayClassName to the GatewayClass of that controller. Set gateway.listenerPort and gateway.tls.listenerPort to the ports that the controller listens on, for example 80 and 443.

To use an Ingress instead, set gateway.enabled: false and configure the ingress values in admin-panel.yaml. See the Admin-panel routing guide.

• Replace the self-signed ClusterIssuer with a production issuer, for example Let's Encrypt (ACME). Set gateway.tls.certManager.issuerRef in admin-panel.yaml to that issuer.
• Replace wproofreader.example.com with your DNS name in admin-panel.yaml (config.appUrl, config.appServerUrl, and gateway.hostnames).
• The demo keeps Admin-panel uploads in the Pod. They are lost when the Pod restarts. For production, enable the persistence PVC (ReadWriteMany) or use S3-compatible object storage. See the Admin-panel chart values.
• The demo sets config.mail.mailer: log. Admin-panel does not send email, and invitation links go to the log of the web Pod. To send email, set the SMTP values.
• MySQL runs as one Pod with an 8 GiB volume and no backups. For production, use a MySQL server that your team operates, for example a managed database service. Then remove the MySQL Application or HelmRelease and set the MySQL host in wproofreader-app.yaml and admin-panel.yaml. Create admin_panel_db and the admin_panel user as the Kubernetes installation guide describes.
• The images come from Docker Hub (webspellchecker/* and mysql). To use a private registry, set image.repository and imagePullSecrets in the values files.
• Push or merge access to this repository (or to your copy) gives administrator access to the cluster. Protect the branch and require reviews.