Skip to main content

How to Update GeoPulse

This guide covers updating GeoPulse to the latest version for both Docker Compose and Kubernetes/Helm deployments.

tip

Always check the GitHub Releases for release notes and breaking changes before updating.

Docker Compose Deployments​

Step 1: Update Version in .env File​

Edit your .env file and update the GEOPULSE_VERSION variable to the desired version:

GEOPULSE_VERSION=1.9.0

Step 2: Pull Images and Restart Services​

You can use the following script to update the backend and frontend services:

#!/bin/bash
set -e

COMPOSE_FILE="docker-compose.yml"
SERVICES="geopulse-backend geopulse-ui"

echo "📥 Pulling latest images for $SERVICES..."
docker compose -f "$COMPOSE_FILE" pull $SERVICES

echo "🛑 Stopping and removing containers for $SERVICES..."
docker compose -f "$COMPOSE_FILE" rm -fsv $SERVICES

echo "🚀 Starting $SERVICES..."
docker compose -f "$COMPOSE_FILE" up -d $SERVICES

echo "✅ Backend and frontend redeployed successfully!"

Save this script as update-geopulse.sh, make it executable with chmod +x update-geopulse.sh, and run it:

./update-geopulse.sh

Database Migrations​

Database migrations are handled automatically when the backend starts up. You don't need to run any manual migration commands.

PostgreSQL Version​

Updating GeoPulse does not change your PostgreSQL version: the GEOPULSE_VERSION in .env only selects the GeoPulse images, and docker-compose.yml keeps its PostgreSQL image. New installations use PostgreSQL 18; installations on PostgreSQL 17 keep working. To move to PostgreSQL 18, follow Upgrading to PostgreSQL 18 after updating GeoPulse.

CORS/OIDC Variable Migration (Compatibility)​

Recent versions introduced explicit CORS and public base URL variables while keeping legacy behavior for existing setups.

PurposeNew variablesLegacy fallbackCompatibility behavior
CORS enable/disableGEOPULSE_CORS_ENABLEDnoneIf not set, backend keeps compatibility default (true). New .env.example sets false.
CORS originsGEOPULSE_CORS_ORIGINSGEOPULSE_UI_URLLegacy fallback still works, but is deprecated.
OIDC callback base URLGEOPULSE_OIDC_CALLBACK_BASE_URLGEOPULSE_PUBLIC_BASE_URL, then GEOPULSE_UI_URLExisting setups continue working; explicit callback URL is recommended.

Recommended post-upgrade actions:

  1. Set GEOPULSE_PUBLIC_BASE_URL to your external URL.
  2. Keep GEOPULSE_CORS_ENABLED=false for standard nginx same-origin deployments.
  3. Use GEOPULSE_OIDC_CALLBACK_BASE_URL explicitly for OIDC deployments.

Kubernetes/Helm Deployments​

Step 1: Update Chart Values​

Update your values.yaml file or chart repository to point to the new version:

image:
  tag: "1.9.0"  # Update to the desired version
PostgreSQL 18

Recent charts use PostgreSQL 18 (postgis/postgis:18-3.6). A release that still runs PostgreSQL 17 must either migrate its data first with the PostgreSQL 18 upgrade script or keep postgres.image.tag: "17-3.5" in its values. Otherwise the postgres pod fails to start (no data is lost).

Step 2: Upgrade with Helm​

Run the Helm upgrade command to deploy the new version:

helm upgrade geopulse ./helm/geopulse -f your-values.yaml

If you're using a remote chart repository:

helm repo update
helm upgrade geopulse geopulse/geopulse -f your-values.yaml

If you installed from the OCI registry:

helm upgrade geopulse oci://ghcr.io/tess1o/charts/geopulse -f your-values.yaml

Step 3: Verify Deployment​

Check that the pods are running with the new version:

kubectl get pods -l app=geopulse
kubectl describe pod <pod-name>

Database migrations are handled automatically by the backend on startup.

Rollback Procedures​

Docker Compose Rollback​

If you need to rollback to a previous version:

  1. Update the GEOPULSE_VERSION in your .env file to the previous version
  2. Run the update script again to deploy the older version

Kubernetes/Helm Rollback​

Use Helm's built-in rollback functionality:

# List release history
helm history geopulse

# Rollback to previous revision
helm rollback geopulse

# Rollback to specific revision
helm rollback geopulse <revision-number>

Version Compatibility​

GeoPulse follows semantic versioning. When updating:

  • Patch versions (e.g., 1.9.0 → 1.9.1): Bug fixes, safe to update
  • Minor versions (e.g., 1.9.0 → 1.10.0): New features, backward compatible
  • Major versions (e.g., 1.9.0 → 2.0.0): Breaking changes, review release notes carefully

Always review the release notes on GitHub Releases before updating, especially for major and minor version changes.