Skip to main content

Quickstart: install GeoLens locally

Follow these steps to go from curl -fsSL https://getgeolens.com/install.sh | sh to a running GeoLens instance with admin access and your first uploaded dataset. You do not need cloud accounts; everything runs locally via Docker Compose.

Not ready to run Docker? Skip the install and browse the live demo

Prerequisites

  • ✓ Docker Compose v2 - ships with Docker Desktop 4.1+ or as a standalone plugin
  • ✓ Open local ports: - 5434 (PostgreSQL), 8001 (API), 8080 (Frontend UI)

Step 1: Run the public installer

Recommended first run:

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

For a source checkout instead, clone the GeoLens repository and run the same installer from the checkout:

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

Or download the release tarball: github.com/geolens-io/geolens/releases/latest

Step 2: Review generated credentials

The public installer clones the latest release tag, pulls prebuilt images, copies .env.example to .env, generates a JWT signing secret, and prompts for an admin username (default admin) and password. Leave the password blank to have a strong one generated for you - retrieve it later with grep '^GEOLENS_ADMIN_PASSWORD=' .env. Source checkouts and branch refs build from source instead of pulling release images. Re-running the installer is idempotent: existing values are preserved, and the script waits until every service is healthy.

Change in production: For anything past local evaluation, set a strong GEOLENS_ADMIN_PASSWORD when prompted (or pre-set GEOLENS_ADMIN_USERNAME and GEOLENS_ADMIN_PASSWORD in the environment for unattended installs) and rotate POSTGRES_PASSWORD in .env.

Step 3: Verify services

Confirm that all default-profile services are healthy before logging in:

docker compose ps

The db, api, worker, titiler, and frontend services should all show running / healthy status.

Step 4: Log in and verify

Open the GeoLens UI in your browser:

http://localhost:8080

Log in with the admin username (default admin) and the password you set or that the installer generated:

  • Username: admin
  • Password: the password you set, or your generated one

The catalog will be empty after a fresh install - that's expected. Upload your first dataset in the next step.

Step 5: Upload your first dataset

Download a tiny public-domain sample - Natural Earth's 1:110m countries shapefile - and upload it through the GeoLens UI. 

curl -LO https://naturalearth.s3.amazonaws.com/110m_cultural/ne_110m_admin_0_countries.zip

In the GeoLens UI, click Create in the header, choose Import Data, and select the ZIP file. GeoLens detects the CRS (EPSG:4326) and schema; confirm the import to publish. The dataset will appear in the catalog and be available through the OGC API at http://localhost:8080/api/collections.

What you'll see

After Step 5, your uploaded dataset appears in the GeoLens catalog. As you add more data the catalog fills out like the one below: searchable dataset cards with type badges and faceted filters. The map preview, metadata panel, and OGC API endpoints at http://localhost:8080/api/collections are all live. Use the search bar to filter datasets, click a card for metadata, and open the map builder to compose multi-layer maps.

A populated GeoLens catalog showing dataset cards (vector and raster) with type badges, a faceted filter sidebar, and the search bar

Step 6 (optional): Load the showcase maps

Want a full catalog instead of a single dataset? The repo ships a seed script that builds six showcase maps from public open data, including the Manhattan 3D skyline from the homepage hero. From the geolens directory the installer created:

pip install httpx
python scripts/seed-showcase.py --username admin --password "$(grep '^GEOLENS_ADMIN_PASSWORD=' .env | cut -d= -f2-)"

Requires internet access to the upstream open-data sources.

Troubleshooting

  • Port conflict - If port 5434, 8001, or 8080 is already in use by another service, edit .env and change DB_PORT, API_PORT, or FRONTEND_PORT to free values. Then run docker compose down && docker compose up -d --build to apply.
  • Admin login fails - Confirm GEOLENS_ADMIN_USERNAME and GEOLENS_ADMIN_PASSWORD in .env match what you're typing. After editing .env, restart services with docker compose restart api.
  • Services slow to start - Release-tag installs pull prebuilt images. Source checkouts build locally and can take longer; watch progress with docker compose logs -f. Subsequent starts reuse cached layers.
  • File upload fails - Confirm the file is one of the supported formats: Shapefile ZIP, GeoPackage, GeoJSON, GeoParquet, CSV, XLSX, or a GeoTIFF/COG raster, or a public OGC service URL. Check the upload dialog for validation errors.

Next steps