Quickstart

GeoLens deploys with one Docker Compose command. This guide takes you from the public installer to a running UI, then shows the source checkout path for development or branch testing.

Prerequisites

• Docker Engine 24.0+ and Docker Compose v2.20+ (verify with docker compose version)
• 8 GB of memory available to Docker (the installer warns below 7 GB)
• Three free host ports (default: 8080, 8001, 5434)

1. Run the public installer

curl -fsSL https://getgeolens.com/install.sh | sh
cd geolens

The one-liner installs the latest published release tag, pulls prebuilt images, copies .env.example to .env, generates a strong JWT_SECRET_KEY (via openssl rand -hex 32) and POSTGRES_PASSWORD, prompts for an admin username (default admin) and password (pressing Enter at the password prompt generates a strong random password rather than reusing a default), and starts the stack. It clones and configures GeoLens into a geolens/ directory, so cd geolens first (as shown above) — every .env and scripts/… command below is relative to that directory. Retrieve a generated admin password with grep '^GEOLENS_ADMIN_PASSWORD=' .env.

If you are installing from a source checkout instead:

git clone https://github.com/geolens-io/geolens.git
cd geolens
bash scripts/install.sh

Source checkouts and branch refs build from source instead of pulling release images. Either way, scripts/install.sh blocks until every service reports healthy, then prints “GeoLens is ready.” Re-running the script is idempotent; existing .env values are preserved.

Which version gets installed

The curl ... | sh one-liner (and any run where the installer clones for you) installs the latest published release tag for a reproducible build. Pin a specific version or track a branch with GEOLENS_REF:

GEOLENS_REF=v1.4.11 bash scripts/install.sh   # a specific release tag
GEOLENS_REF=main   bash scripts/install.sh   # track the main branch

Running bash scripts/install.sh from inside an existing git clone instead builds whatever that checkout has (the main branch by default).

Admin credentials: interactive vs unattended

install.sh decides whether to prompt based on whether a controlling terminal is reachable — it reads from /dev/tty, not stdin, so piping the script through sh does not by itself make the run unattended:

• Interactive (the usual case): whenever /dev/tty is writable — including a piped curl … | sh launched from your terminal — the script prompts for an admin username (default admin) and password. Pressing Enter accepts the default username, but leaving the password blank generates a strong random password (it is never set to admin). Retrieve it later with grep '^GEOLENS_ADMIN_PASSWORD=' .env.

• Unattended (no controlling terminal): in CI, under nohup/systemd, or any process with no /dev/tty, the prompt is skipped and the script reads GEOLENS_ADMIN_USERNAME and GEOLENS_ADMIN_PASSWORD from the environment. Set both before running:

  export GEOLENS_ADMIN_USERNAME=admin
  export GEOLENS_ADMIN_PASSWORD=$(openssl rand -base64 16)
  bash scripts/install.sh

If neither the env vars nor a TTY prompt supply a password, the installer generates a strong random admin password and writes it to .env. Retrieve it with grep '^GEOLENS_ADMIN_PASSWORD=' .env. The username still defaults to admin.

For the full list of configuration options, see Configuration.

Manual install (without scripts/install.sh)

If you’d rather configure .env by hand, copy .env.example to .env, generate a JWT secret with openssl rand -hex 32 and paste it as JWT_SECRET_KEY=..., fill in GEOLENS_ADMIN_USERNAME and GEOLENS_ADMIN_PASSWORD (both ship empty, and the API refuses to start until they’re set), then run docker compose up -d.

2. Verify services

docker compose ps

Confirm db, api, worker, titiler, frontend, and backup show as running / healthy before logging in. The one-shot migrate job runs first and exits, which is expected.

Apple Silicon (arm64) hosts

On Apple Silicon Macs (M1 / M2 / M3 / M4), docker compose up emits this warning during the first image pull:

The requested image's platform (linux/amd64) does not match the detected
host platform (linux/arm64/v8) and no specific platform was requested

This is expected and harmless. The db image (Postgres + PostGIS) and a couple of supporting images are amd64-only; Docker Desktop runs them under Rosetta 2 emulation. The stack works correctly, though you may see slightly slower postgres startup compared to a native amd64 host. No action needed.

3. First login

Open http://localhost:8080. Log in with the admin username (default admin) and the password you chose during install. If the installer generated one, retrieve it with grep '^GEOLENS_ADMIN_PASSWORD=' .env.

Caution

If you set the admin password yourself, consider rotating it after first login. Navigate to Admin -> Users in the running app to change credentials. Never expose a reachable host with a weak or shared admin password.

After logging in, follow the admin password rotation guide to rotate or replace the bootstrap admin account.

The login page proves you’ve reached the frontend at http://localhost:8080. Look for the centered username/password card with the GeoLens reticle logo at the top. After login, a fresh local install shows an empty catalog, which is expected. Use the seeder scripts in the next section to populate it.

4. Seed sample data

After login, your catalog is empty. The fastest way to populate it is the bundled scripts/seed-showcase.py script. It builds six showcase maps from public, openly licensed data by writing into a running GeoLens instance via its API, plus a few catalog-only datasets, two collections, and a small embed-token demo: a deliberately private map and dataset whose scoped embed token is printed at the end of the run, so seeing them is expected. It needs no separate stack or compose file.

| Showcase map | What it demonstrates | Source | |---|---|---| | Restless Earth | multi-layer composition: filtered quake/volcano layers, a heatmap, and a server-styled relief COG | USGS, PB2002, NCEI, ETOPO 2022 | | Manhattan - A Century of Skyline | 3D fill-extrusion at true roof height, colored by construction era, over the subway | NYC Open Data, MTA | | The Matterhorn in 3D | 3D terrain mesh + hillshade from a VRT mosaic of COG tiles | swisstopo swissALTI3D 2m lidar | | Hurricane Alley | categorical styling of 75 years of hurricane tracks, with arrow rendering and line labels | NOAA HURDAT2 | | Everything That Fell From the Sky | server-side cluster tiles over ~32k meteorite landings | NASA / Meteoritical Society | | New York From Orbit | Sentinel-2 true-color imagery imported by reference from a STAC API | Element 84 Earth Search |

The examples repo’s embed/iframe.html embeds the demo’s copy of Restless Earth, so you can see the share-and-embed step before building it.

Seeder prerequisites

The seeder is a Python script that talks to the running GeoLens via its API. You’ll need Python 3.10 or newer on your host machine (check with python3 --version) and the httpx package, installed into a virtual environment in the next step.

The seeder runs on your host, not inside the docker network. It targets http://localhost:8080 by default; pass --base-url <url> to point at a different deployment.

Run the demo seeder

First make the admin password available to your shell — if the installer generated it, load it out of .env (run this from the geolens/ directory):

export GEOLENS_ADMIN_PASSWORD=$(grep '^GEOLENS_ADMIN_PASSWORD=' .env | cut -d= -f2-)

Then install httpx into a virtual environment and run the seeder with it. A venv is the reliable path because recent Python builds — Homebrew on macOS, and Debian/Ubuntu — refuse pip install into the system interpreter (PEP 668). On Debian/Ubuntu, install the venv module first with sudo apt install python3-venv:

python3 -m venv .venv
.venv/bin/pip install httpx
.venv/bin/python scripts/seed-showcase.py --username admin --password "$GEOLENS_ADMIN_PASSWORD"

Or, with uv, one line handles the dependency with no venv to manage:

uv run --with httpx scripts/seed-showcase.py --username admin --password "$GEOLENS_ADMIN_PASSWORD"

The script authenticates with your admin username (default admin) and password. Pass the password you set or that the installer generated via --password (or set GEOLENS_ADMIN_PASSWORD in your environment). By default it builds all six showcase maps. Three flags trim the heavier downloads for a faster or lower-bandwidth seed: the Matterhorn terrain hero downloads ~62 COG tiles (--no-terrain skips it), the Restless Earth relief backdrop is a ~466 MB ETOPO 2022 download on the worker (--no-oceans skips just that layer), and the Sentinel-2 map is imported by reference with zero download but needs Titiler to reach AWS S3 at view time (--no-sentinel2 skips it):

.venv/bin/python scripts/seed-showcase.py --no-terrain --username admin --password "$GEOLENS_ADMIN_PASSWORD"

Use --only to build a single item - for example --only manhattan, --only matterhorn, or --only meteorites.

Once the seeder finishes, reload http://localhost:8080. The catalog is now populated and searchable, with type, keyword, and spatial filters down the left rail:

Select any dataset card to open its detail page: metadata, schema, and a live map preview of the data’s extent. The screenshot below shows the detail page for the Sentinel-2 satellite imagery referenced by the New York From Orbit showcase map:

Service topology

The default docker compose up -d brings up seven services: six long-running (shown below) plus a one-shot migrate job that applies database migrations and exits. The diagram below shows how the long-running services connect; MinIO and Valkey appear only when you opt into --profile cloud-dev.

Next steps

• Going to production? See the Install Guide for full prerequisites, default services, optional profiles, and troubleshooting.
• Configuring users and roles? See the Admin Guide for RBAC, OAuth/OIDC, and backup automation.
• Building integrations? See the API Reference for OGC endpoints, authentication, and curl examples.
• Want running code? The examples gallery has working clients for the catalog and APIs you just stood up, arranged by tool.