Downtime Upgrade SOP

This page provides a reference SOP for downtime upgrades. Adapt it to your production standards if needed.

Docker Compose Upgrade

Preparation

• Choose the target version and check config changes in Production Deployment
• Prepare a new .env.custom (keep the old one for rollback)
• Prepare license files
• Notify users of the maintenance window

Upgrade Steps

1. Block Writes and Stop Old Version

   Block new requests to avoid data inconsistency.

   Edit universer-old/nginx/universer.conf and add:

   NGINX

   location ~ ^/universer-api {return 403;}

   Reload Nginx:

   Bash

   docker exec univer-lb nginx -s reload

   Wait at least 1 minute, then stop the old services:

   Bash

   cd universer-old && bash run.sh stop

2. Data Backup

   Backup RDS metadata (object storage is append-only; backup if needed).

3. Deploy New Version

   • Download the target version (online or offline)
   • Copy the new .env.custom
   • Place license files under configs/
   • If using self-managed RDS, run DB upgrade scripts

   To allow only test accounts, add to nginx/universer.conf:

   NGINX

   underscores_in_headers on;if ($http_x_request_env != "test") {  return 403;}

   Start the new version:

   Bash

   bash run.sh start

Post-Upgrade Validation

• Verify key flows with x-request-env=test
• Monitor logs and metrics

Cutover

Remove the header restriction and reload Nginx:

docker exec univer-lb nginx -s reload

Rollback

• Stop the new version
• Restore old Nginx config
• Start the old version

K8s Upgrade

Preparation

• Prepare a new values.yaml (keep the old one)
• Prepare license files
• Notify users of the maintenance window

Upgrade Steps

1. Block Access to Old Version

   Disable ingress in the old config:

   YAML

   universer:  ingress:    enabled: false

   Apply it with the current chart version:

   Bash

   helm upgrade univer-stack \  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \  --version your-current-version \  -n univer \  -f values-1.0.0-forbid.yaml \  --set-file universer.license.licenseV2=your-license.txt-path \  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path

   Find the current chart version via helm list --all-namespaces --filter univer-stack.

2. Data Backup

   Backup RDS metadata.

3. Upgrade to New Version

   To allow only test users, add to the new config:

   YAML

   universer:  ingress:    enabled: true    annotations:      nginx.ingress.kubernetes.io/configuration-snippet: |        if ($http_x_request_env != "test") {          return 403;        }

   Upgrade:

   Bash

   helm upgrade --install univer-stack \  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \  --version target-version \  -n univer \  -f your-values.yaml-path \  --set-file universer.license.licenseV2=your-license.txt-path \  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path

   For offline scenarios, use the offline bundle and run bash load-image.sh.

Post-Upgrade Validation & Cutover

• Validate with test account
• Remove ingress restriction and re-apply

Rollback

Use the old chart version and config:

helm upgrade --install univer-stack \  oci://univer-acr-registry.cn-shenzhen.cr.aliyuncs.com/helm-charts/univer-stack \  --version old-version \  -n univer \  -f old-values.yaml \  --set-file universer.license.licenseV2=your-license.txt-path \  --set-file universer.license.licenseKeyV2=your-licenseKey.txt-path