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:
Terminal window
# From your install directory
./scripts/upgrade.sh# upgrade to the newest published release
./scripts/upgrade.sh1.13.0# or pin an explicit target version
scripts/upgrade.sh (equivalently, bash scripts/install.sh --upgrade) performs, in order:
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).
Pins the new GEOLENS_VERSION in .env.
Pulls the prebuilt images (docker compose pull --ignore-buildable).
Runs migrations via the fail-closed one-shot migrate service. A failed migration aborts before the app is started.
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.
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.)
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 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 neverpsql < 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.
Terminal window
# 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.12.0
# 2. Restore the pre-upgrade dump the upgrade created. restore.sh stops
# api/worker, runs pg_restore, and restarts them afterward.
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.
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:
Terminal window
# 1. Update the checkout to the new release tag.
gitfetch--tagsorigin
gitcheckoutv1.13.0# replace with your target tag
# 2. Rebuild the images from the new source.
dockercompose-fdocker-compose.ymlbuild
# 3. Run migrations (fail-closed) BEFORE starting the app.
dockercompose-fdocker-compose.ymlup-dmigrate
dockercompose-fdocker-compose.ymllogsmigrate# confirm it exited 0
# 4. Bring the stack up and verify health.
dockercompose-fdocker-compose.ymlup-d
dockercompose-fdocker-compose.ymlps
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.
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.13.0: extension API version 7; dataset delete detaches registered tables
Overlay packages must be rebuilt. The extension API version is now 7.
An overlay built against an earlier version is refused at load, so rebuild
every overlay package before deploying this release. Installs without
overlay packages are unaffected.
Deleting a registered dataset no longer drops its table. The catalog
row, grants, tiles, and caches are removed while the operator’s physical
table survives. Datasets GeoLens ingested itself are still dropped in full.
The delete dialog states which of the two will happen. If you had scripted
around the old drop-everything behavior, re-check it.
1.12.0: raster CRS override assigns instead of reprojecting
A raster CRS override now assigns the CRS rather than reprojecting to
it. Supplying an EPSG code at import or replace time relabels the raster
in place: pixel values, the pixel grid, and the corner coordinates all pass
through untouched, and only the CRS they are read under changes. A dataset
ingested with an override therefore lands wherever those coordinates put it
in the CRS you named, which may not be where the same override put it
before. Rasters are still reprojected at serve time and at export time;
reproject-at-ingest is not offered. Re-check any ingest automation that
passed an override expecting a reprojection.
Because the conversion no longer resamples, the uploaded file is deleted
after a successful lossless ingest instead of being kept as a second
permanent copy.
Migration 0041 is a data migration. It rewrites stored WKT1 CRS
definitions to WKT2:2019 in batches; deploy logs report
converted to WKT2:2019: N row(s). The downgrade is a no-op.
1.11.0: shared credential store for protected service refreshes
Passing a service token to a refresh now requires REDIS_URL
(Valkey/Redis), so the credential can reach the worker without touching
disk. Deployments that only refresh public sources need no change.
1.10.0: PROMETHEUS_MULTIPROC_DIR for multi-worker metrics
New env var, required for multiprocess metrics: PROMETHEUS_MULTIPROC_DIR.
Both the dev and prod Compose files set it to a tmpfs-backed path. On a
custom deployment running UVICORN_WORKERS > 1, point it at a writable
directory that is empty on boot, or /metrics serves single-process
(non-aggregated) counters.
Pull or rebuild before recreating the api container. The entrypoint
script that prepares the directory ships in the image, not in the Compose
file, so recreating api to pick up the new variable without a new image
fails to boot.
1.7.0: restart the backup container; two endpoint shapes changed
Restart the backup container once after upgrading (any full stack
restart covers it). The backup daemon reads its entrypoint at container
start, so an already-running daemon keeps the old cycle and will not
produce the new globals-*.sql role dump until it restarts. That artifact
is what makes a fresh-cluster restore work — see
Backups & restore.
Antimeridian-crossing extents are now served in RFC 7946 spec form, a
bbox with west > east (e.g. [178, -19, -178, -17] for Fiji) at the
dataset and collection endpoints, instead of a flattened [-180, …, 180]
span. Clients that assume west <= east need to handle the wrap.
GET /tiles/raster-auth-check/ is gone from the API contract and both
SDKs. Anyone calling it directly should use the raster tile URL from
GET /tiles/token/{dataset_id}/ instead.
DEMO_MODE is ignored. The Demo Mode banner was replaced by the
admin-configurable Site Banner (Settings -> General), which carries custom
text, a color choice, and per-session dismissal. Env-only deployments
configure it with BANNER_ENABLED, BANNER_TEXT, and BANNER_COLOR. The
/api/auth/config response no longer includes the demo_mode field.
Set BACKUP_MAX_AGE_MINUTES if you run a non-daily BACKUP_SCHEDULE.
The backup container now reports unhealthy when backups stop succeeding,
judged against this setting (default 1560 minutes = 26 hours, sized for the
default daily schedule). Roughly 1.5x your backup interval is the right
value.
1.5.0: PostgreSQL 18 + PostGIS 3.6 (breaking for self-hosted)
scripts/upgrade.sh does not apply to this release. The bundled database
moved from PostgreSQL 17 + PostGIS 3.5 to PostgreSQL 18 + PostGIS 3.6. An
existing PG 17 pgdata volume cannot be opened by PG 18, so the upgrade is a
dump -> fresh volume -> restore, not an image pull.
Bundled-database installs: follow the procedure in
RUNBOOK.md section 6.
scripts/upgrade.sh compares the running server’s major version against the
one the target release bundles and stops before anything changes — no
image pull, no version pin, no database write — printing that procedure
instead.
Managed or external database installs (DATABASE_URL_OVERRIDE): the
check is skipped, since the bundled image’s version says nothing about the
database you actually use. Run your provider’s PostgreSQL 17 -> 18 upgrade,
then deploy as usual. The minimum supported external version remains
PostgreSQL 13.
The backup image’s pg_dump moves to 18 in lockstep, because a v17
pg_dump cannot dump a PG 18 server.
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.
DATABASE_SSL_MODE now fails closed. The undocumented allow and
verify-ca values no longer boot; switch to prefer or verify-fullbefore 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.
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:
Terminal window
echo-n"$JWT_SECRET_KEY"|wc-c
If it reports fewer than 32, generate a replacement and update your .env:
Terminal window
JWT_SECRET_KEY=$(opensslrand-hex32)
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.
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).
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.