Skip to main content

Patching guide

This guide takes you through patching MintPress to the latest release. Patch one release at a time: skipping releases may result in data loss and unexpected behaviour.

Steps for the release you are upgrading from​

Some upgrades need steps of their own before or after helm upgrade. Find the release you are running now in the table below and carry out its steps along with this guide. A release that is not listed needs none. Check the release notes for the release you are upgrading to as well, for breaking changes that affect your actions, integrations or authorisation rules.

Upgrading fromSteps
2026-10-08Run the secret vault settings check, stop MintPress for the upgrade, and update your values.yaml. See patching from 2026-10-08.
2026-09-14Remove openbao.server.image.tag from your values.yaml, and plan a short outage, as the database and the secret vault restart. See the 2026-10-08 release notes.
2026-08-20Schedule downtime, as the API workers are stopped while the database is migrated, and make sure your LDAP directory is reachable. See the 2026-09-10 release notes.
2026-08-14Rename one of any two actions in a namespace that share a step name, ignoring case, and write a / in a step name as _ in skip_steps patterns and starting_step values. See the 2026-08-20 release notes.
2026-08-10Make template codes unique within each project, check that the secret vault hostname resolves inside the cluster, set global.ingressTlsPort if a load balancer translates the ingress port, and rebuild custom runner images after upgrading. See the 2026-08-14 release notes.
2026-08-04Re-apply the CloudNativePG operator manifest. See the 2026-08-10 release notes.

Prerequisites​

To patch MintPress, we must refer to the values.yaml file used for installation. The patching process should be performed in the same server as the one used for installation.

If you're patching a high availability topology, ensure you follow the patch sequence instructions.

Validate Helm and K3s are installed​

Before you proceed, please ensure Helm and K3s are installed and configured. You can quickly verify this by running the following commands:

helm version
k3s --version

If you see the version numbers, you are good to go. If you don't, please refer to the Installing K3s guide for more information.

Validate Helm registry access​

With the credentials you received as part of your licence, ensure Helm is connected to DockerHub's registry.

helm registry login docker.io

The command will prompt you for your DockerHub credentials.

MintPress chart version​

Identify the version of MintPress you want to patch to from the Release Notes page and set it to your bash profile with the Helm chart version format, for example:

vi ~/.bash_profile

And then add or modify the following line with the version you want to upgrade to:

export MINTPRESS_CHART_VERSION=2025.11.12

Then source it for the changes to take effect:

source ~/.bash_profile

Update the values.yaml file​

You can obtain the new values.yaml file in the sample values.yaml files section of this documentation. You can download it with:

curl -L https://docs.mintpress.io/files/config_file_examples/values.yaml.example -o /limepoint/values_new.yaml

Some MintPress updates might change the settings in the values.yaml file. To ensure you don't lose any of your custom settings, merge the new values_new.yaml file with the one you used for installation (or previous patches), ensuring the new settings are applied and your custom settings are preserved. Save the merged file as values.yaml so that it can be used in the next step.

Refer to the release notes for the version you're patching to for any new settings that need to be applied or breaking changes. If you are unsure, refer to the configuration guide for more information.

To see the settings the release ships with, download the full values.yaml for this version of the documentation and compare it against your own file.

Keys cannot change

Keep the mandatory encryption keys and passwords exactly as they were when MintPress was installed. The upgrade fails if any of them differs.

MintPress version

Ensure all the settings that have an image tag match the MintPress version you're patching to, otherwise your installation will be running with outdated images.

The secret vault is the exception: do not set openbao.server.image.tag. Each MintPress release chooses the secret vault image itself, and only changes it when the secret vault software is updated, so most upgrades leave the secret vault running. An upgrade that does change it restarts the secret vault, which cannot be reached for a few seconds while the new image is downloaded and the vault starts. Remove the setting if your values.yaml contains it.

Patch MintPress​

With the environment variables configured and the values.yaml file updated, patch MintPress to the latest version by running the following command:

helm upgrade --install mintpress "oci://docker.io/limepoint/mintpress" --version ${MINTPRESS_CHART_VERSION} --create-namespace -n ${KUBERNETES_NAMESPACE} -f /limepoint/values.yaml --wait --timeout 30m --insecure-skip-tls-verify --debug
Patching time

The command may take several minutes (up to 30 mins) to start as the MintPress images are downloaded, especially with slower internet connections.

Do not close or end the shell session while the patching is still ongoing, doing so might render your installation unusable.

Just like with installation, this command will start the MintPress server and its dependent services in separate Kubernetes pods. For more information on these containers see the architecture overview.

The kubectl command can be used to see the patching progress:

kubectl get deployments.apps/opschain-api -n ${KUBERNETES_NAMESPACE}

The patching will be complete when the READY column of the opschain-api deployment is set to 1/1. You can verify the current MintPress version in the version info section of the GUI.

Patching a high availability topology​

The steps above patch a single cluster. In a high availability topology several clusters share one replicated database, and every MintPress instance — including those running in replica clusters — connects to the primary cluster's database. Each OpsChain API applies any outstanding database migrations automatically as it starts, against that shared database.

Two consequences shape how you patch:

  • The schema is migrated once, by the first patched API to start. Every other running instance then uses that same, already-migrated schema.
  • Running two different MintPress versions against the shared database at the same time is unsafe — an older instance can encounter a schema it does not expect. Patch the primary first, and keep the window in which clusters run different versions as short as possible.
Patch the whole topology in one maintenance window

Treat the topology's MintPress instances as a single application. Do not leave some clusters on the old version and others on the new version for longer than the patching itself takes.

Before you patch a topology​

  • The steps for the release you are upgrading from and the release notes breaking changes apply to the whole topology — carry them out before you start.
  • Move every cluster's values.yaml to the same new version together, keeping the encryption keys, database credentials and image registry password identical across clusters, as high availability already requires.
  • Do not failover during patching.
  • If the release changes the PostgreSQL major version, streaming replication cannot run between clusters on different majors — plan this separately and follow the release notes' guidance. See db.cnpg.imageName.

Patch sequence​

  1. Update the values.yaml on every cluster to the new version, as described above.

  2. Reduce the running application to only the primary cluster. Scale the API and workers to 0 in every replica cluster and, if you run MintPress instances (API, workers) in replica clusters, put those clusters into stopped mode (stopped: true) so only the primary cluster runs the application while the database is migrated. Their databases keep replicating.

  3. Patch the primary cluster with the patch command. Its API applies the database migration against the shared database. Wait until opschain-api reports 1/1.

  4. Patch each replica cluster to the same version with the same command. If you run MintPress instances there, bring them back by removing stopped: true. Because the schema is already migrated, the new code matches it.

  5. Verify every database cluster is healthy and replicating (kubectl get cluster <cluster-name> -n ${KUBERNETES_NAMESPACE}), confirm the version info, and make a small write — create a change or edit a project's properties — to confirm the primary is serving.

Minimising database downtime

Upgrading the primary cluster might restart its database instance in some scenarios, which briefly interrupts the database. If you run more than one database instance in the primary cluster (via db.cnpg.instances), set db.cnpg.primaryUpdateMethod to switchover to reduce that interruption.

If opschain-api does not become ready and the patching times out while you are using the OpsChain secret vault, see helm upgrade fails with context deadline exceeded.

Old images in the OpsChain registry​

MintPress will not automatically remove old images in the internal image registry during the patching process. This means that old runner images may still exist in the registry, using up disk space. If you need to remove these old images, refer to the container image cleanup guide.

Troubleshooting​

If the Helm commands take too long to complete, you can check the status of the deployments with the following command:

kubectl get deployments.apps -n ${KUBERNETES_NAMESPACE}

And verify that all deployments have the READY column set to a matching value, for example:

NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/opschain-api 1/1 1 1 10m
deployment.apps/opschain-api-worker 2/2 2 2 10m
...

To check the status of the pods, you can run the following command:

kubectl get pods -n ${KUBERNETES_NAMESPACE}

Common issues​

Build service pod stuck in Pending state​

If the buildService.rootless setting is set to true in your values.yaml file, it might occur that the build service pod gets stuck in a Pending state. This is usually related to the fuse-device-plugin-daemonset not running or requiring a restart. This pod is responsible for making the required FUSE devices on the node, available to the opschain-build-service pod when running in rootless mode.

If this is the case, the opschain-build-service pod will show events similar to the following:

Warning FailedScheduling 22m default-scheduler 0/1 nodes are available: 1 Insufficient github.com/fuse. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.
Warning FailedScheduling 6m23s (x7 over 22m) default-scheduler 0/1 nodes are available: 1 Insufficient github.com/fuse. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.
Solution - restart the fuse-device-plugin-daemonset daemonset​

To restart the fuse-device-plugin-daemonset daemonset, run the following command:

kubectl rollout restart daemonset/fuse-device-plugin-daemonset -n ${KUBERNETES_NAMESPACE}

This will restart the daemonset and make the FUSE devices available to the opschain-build-service pod.