Upgrade Guide

How to upgrade GeoLens between versions.

Standard upgrade

Most GeoLens installs are prebuilt-image installs, the ones created with curl -fsSL https://getgeolens.com/install.sh | sh. Their .env records COMPOSE_FILE=docker-compose.prod.yml and a pinned GEOLENS_VERSION. For these, the recommended upgrade is the one-command, backup-first flow:

# From your install directory
./scripts/upgrade.sh            # upgrade to the newest published release
./scripts/upgrade.sh 1.3.0      # or pin an explicit target version

scripts/upgrade.sh (equivalently, bash scripts/install.sh --upgrade) performs, in order:

1. Pre-upgrade backup. Quiesces api + worker, then pg_dump -Fc to a timestamped file under backups/pre-upgrade/. The upgrade aborts if the dump is missing or empty (nothing else is touched).
2. Pins the new GEOLENS_VERSION in .env.
3. Pulls the prebuilt images (docker compose pull --ignore-buildable).
4. Runs migrations via the fail-closed one-shot migrate service. A failed migration aborts before the app is started.
5. Starts the stack and waits for every service to report healthy.

On success it keeps the pre-upgrade dump and prints the rollback recipe for reference; on any failure it stops, leaves your data in the dump, and prints the same recipe.

If you instead build from source (git clone install, COMPOSE_FILE=docker-compose.yml), upgrade by updating the checkout and rebuilding. See Source-build upgrade below. scripts/upgrade.sh detects a source install and prints those instructions instead of running.

Check which path you are on:

grep -E '^(COMPOSE_FILE|GEOLENS_VERSION)=' .env

Major version upgrades

Major versions may include breaking changes. Always read the changelog and release notes for the target version before upgrading.

Pre-upgrade checklist

1. Back up your database before any major upgrade. Use a custom-format (-Fc) dump, the format scripts/restore.sh expects for rollback. (scripts/upgrade.sh takes this backup for you automatically; this is the manual equivalent.)

   mkdir -p backups/pre-upgrade
   docker compose -f docker-compose.prod.yml exec -T db \
     pg_dump -U geolens -d geolens -Fc --no-owner --no-acl \
     > "backups/pre-upgrade/geolens_$(date +%Y%m%d_%H%M%S).dump"

2. Review the changelog for breaking changes, removed features, or required configuration changes.

3. Check .env.example for new required environment variables. Compare with your current .env:

   diff <(grep -v '^#' .env.example | grep -v '^$' | cut -d= -f1 | sort) \
        <(grep -v '^#' .env | grep -v '^$' | cut -d= -f1 | sort)

4. Run the upgrade (prebuilt install). The one command does the backup, version bump, image pull, fail-closed migration, and health gate:

   ./scripts/upgrade.sh 1.3.0      # replace with your target version

5. Verify all services are healthy:

   docker compose ps
   curl -fsS http://localhost:8080/api/health | jq .status   # expect: "healthy"

   Use /api/health (proxied to the API), not a bare /health — through the bundled Nginx a bare /health is answered by the frontend SPA with HTML and status 200, so it can never fail even when the API is down.

Rollback

Rollback is re-pin the previous version + restore the pre-upgrade -Fc dump. Schema migrations move forward only; alembic downgrade is not a supported rollback, and you must never psql < dump a custom-format (-Fc) file (it is not plain SQL). Restore with scripts/restore.sh, which validates the dump and restores it via pg_restore.

# 1. Re-pin the previous version in .env (edit the GEOLENS_VERSION= line).
#    Image tags are bare semver, e.g. the version you upgraded FROM:
#    GEOLENS_VERSION=1.2.4

# 2. Restore the pre-upgrade dump the upgrade created. restore.sh stops
#    api/worker, runs pg_restore, and restarts them afterward.
./scripts/restore.sh backups/pre-upgrade/geolens_pre_<old>_to_<new>_<timestamp>.dump

# 3. Bring the previous version back up.
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps

A failed scripts/upgrade.sh run prints this exact recipe (with the real dump path filled in) before it exits, so you can copy it from the upgrade output.

Source-build upgrade (alternative)

For installs that build from source (COMPOSE_FILE=docker-compose.yml), upgrade by updating the checkout and rebuilding instead of pulling images. Take a -Fc backup first (step 1 above), then:

# 1. Update the checkout to the new release tag.
git fetch --tags origin
git checkout v1.3.0            # replace with your target tag

# 2. Rebuild the images from the new source.
docker compose -f docker-compose.yml build

# 3. Run migrations (fail-closed) BEFORE starting the app.
docker compose -f docker-compose.yml up -d migrate
docker compose -f docker-compose.yml logs migrate   # confirm it exited 0

# 4. Bring the stack up and verify health.
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

To roll a source build back, restore the -Fc dump with scripts/restore.sh (as above) and git checkout the previous tag, never alembic downgrade.

Version-specific notes

Each release’s authoritative upgrade notes live in the CHANGELOG under that version’s Upgrade notes heading. The notes below cover the releases with material operator action.

1.4.8: PostgreSQL max_connections raised to 80

• max_connections is raised to 80 in the bundled db/postgresql.conf to cover the API-side job-queue connector. Recreate or restart the db container after upgrading so the new value takes effect. A running container keeps its old limit until it restarts.

1.4.7: database SSL modes fail closed; migrations 0018–0024

• DATABASE_SSL_MODE now fails closed. The undocumented allow and verify-ca values no longer boot; switch to prefer or verify-full before upgrading.
• Back up before applying migrations 0018 through 0024. The standard scripts/upgrade.sh flow takes this backup automatically. These migrations add tenant identifiers, database roles, row-security policies, and tenant data-schema support; default single-tenant deployments keep their current behavior.
• Run these migrations with a database role that can create roles. Managed-PostgreSQL users may need a separate migration credential with CREATEROLE; keep the API and worker on their existing least-privilege runtime credential. On a busy database, lock-sensitive steps time out after five seconds instead of queueing behind application traffic — retry during a quieter window if that happens.

1.0.0: JWT_SECRET_KEY minimum length

The backend now enforces a 32-character minimum on JWT_SECRET_KEY at startup (HS256 requires >= 256 bits of entropy). A deployment with a shorter secret will fail fast on the next restart with:

FATAL: JWT_SECRET_KEY must be at least 32 characters. Generate one with: openssl rand -hex 32

Before upgrading, verify your secret length:

echo -n "$JWT_SECRET_KEY" | wc -c

If it reports fewer than 32, generate a replacement and update your .env:

JWT_SECRET_KEY=$(openssl rand -hex 32)

Rotating the key invalidates all issued JWT tokens. All users will be logged out and need to sign in again. Plan the rotation during a low-traffic window, or coordinate with your user base.

.env.example ships JWT_SECRET_KEY= empty, and the validator also rejects well-known public placeholders such as dev-only-change-me-in-production. scripts/install.sh generates a real openssl rand -hex 32 secret on first run, so installer-driven deployments are unaffected; hand-edited .env files must set a real openssl rand -hex 32 value.

Other env hardening in this release:

• Secret fields (POSTGRES_PASSWORD, JWT_SECRET_KEY, GEOLENS_ADMIN_PASSWORD, ANTHROPIC_API_KEY, OPENAI_API_KEY, S3_SECRET_ACCESS_KEY, TILE_SIGNING_SECRET) are now stored as Pydantic SecretStr internally. Values are masked in logs, repr(), and validation-error output. Application behavior is unchanged; this is a defense-in-depth improvement.
• LOG_LEVEL values are now validated against the stdlib logging set (DEBUG, INFO, WARNING, ERROR, CRITICAL). A typo like LOG_LEVEL=verbose now fails at startup instead of crashing later.
• ENV_ONLY_CONFIG is now documented in .env.example. It is optional.
• The backend/.env symlink has been removed. Host-side workflows (cd backend && uv run pytest) now resolve ./.env at the project root via the Settings env_file path. No action required unless you had local scripts depending on backend/.env as a literal path.
• VITE_API_PROXY_TARGET (docker-compose.yml frontend service) was renamed to API_PROXY_TARGET. The old name still works for one release via a fallback in vite.config.ts; update your local compose overrides when convenient.

1.0.0: Landing page removal

The landing page has been removed. The root route (/) now serves the Search page directly. The SHOW_LANDING_PAGE environment variable has been removed from backend config and the branding API.

What this means:

• Existing bookmarks to / will show the Search page instead of the landing page.
• The /search route redirects to /; existing /search bookmarks continue to work.
• Remove SHOW_LANDING_PAGE from your .env if present (it is ignored but produces no error).

About 1.0.0 (the public release)

GeoLens 1.0.0 is the first public release. Prior to 1.0.0, the project was internally versioned as 2.0 -> 13.0 during pre-public development. Those legacy versions never shipped to anyone outside the project.

If you somehow have a checkout from a pre-1.0.0 internal build:

• No data migration is required. The 1.0.0 schema is compatible with the most recent pre-public versions; Alembic migrations apply normally on the first 1.0.0 startup.
• The version number resets, but the codebase moves forward. 1.0.0 is the cumulative state of all prior internal work, not a downgrade.
• No git checkout v13.x rollback path exists from 1.0.0. If you need to roll back, restore from the database backup you took before upgrading (see Pre-upgrade checklist).
• No environment variables changed at the 1.0.0 boundary. Your existing .env from any pre-public build continues to work without modification.

For all subsequent upgrades, follow the standard procedure above.

v12.x -> v13.0

• Security hardening: CORS configuration tightened. If you use cross-origin API access, verify CORS_ALLOWED_ORIGINS is set in your .env.
• Docker images: Base images pinned to specific digests. Rebuild with --build flag.

v10.x -> v11.0

• Performance optimizations: New database indexes added via migration. The migration may take a few minutes on large datasets.

v9.x -> v10.0

• Raster support: New titiler service added to docker-compose.yml. Ensure your deployment includes this service for raster/COG tile rendering.