Quickstart

GeoLens deploys with one Docker Compose command. This guide takes you from a fresh checkout to a running UI in about 10 minutes.

Prerequisites

• Docker Engine 24+ and Docker Compose v2 — verify with docker compose version
• 4 GB RAM and 10 GB free disk for the base stack
• Three free host ports (default: 8080, 8001, 5434)

For production-grade sizing, see Resource Sizing.

1. Clone and configure

git clone https://github.com/geolens-io/geolens.git
cd geolens
cp .env.example .env

Generate a strong JWT secret before you start, then paste the output into .env as JWT_SECRET_KEY:

openssl rand -hex 32

The shipped .env.example boots with GEOLENS_ADMIN_USERNAME=admin and GEOLENS_ADMIN_PASSWORD=admin for local development. Change both before you expose this instance to anything but localhost.

For the full list of configuration options, see Configuration.

2. Start services

docker compose up -d

This brings up the default-profile services (database, API, worker, titiler, frontend). The first run takes 1-2 minutes to build images and run database migrations. Subsequent starts use the cached images.

3. First login

Open http://localhost:8080. Log in with the credentials you set in .env:

• Username: GEOLENS_ADMIN_USERNAME (defaults to admin)
• Password: GEOLENS_ADMIN_PASSWORD (defaults to admin)

Caution

Rotate the default admin password immediately after first login if you used the shipped admin placeholder. Navigate to Admin → Users in the running app to update — leaving the default in place on any reachable host is the single most common GeoLens self-host misconfiguration.

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

What you should see

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, the catalog shows your seeded or uploaded datasets — search, filter by tag, and click into any record to see details.

The dataset detail page surfaces the map preview, metadata, and export options all at once.

Service topology

The default docker compose up -d brings up five services. The diagram below shows how they connect; profile-gated services (backup, MinIO, Valkey) appear only when you opt into them via --profile <name>.

Try the themed demo

GeoLens ships with three themed collections — Planet Earth, Global Development & People, and Borders, Boundaries & Contested Space — and nine signature maps that load deterministically with one command:

cp .env.demo .env
docker compose -f docker-compose.yml -f docker-compose.demo.yml up -d --build

Note

The seeder image bakes datasets at build time. First run takes ~10-15 minutes on a fast connection (most of it is the GEBCO 2024 ocean-floor download). Subsequent rebuilds are cached.

After the seeder image finishes building, open http://localhost:8080 and navigate to Maps. The signature stories include:

• Earth as Seen from Space — bathymetry + topography + ice on a dark world view
• Global Bathymetry — GEBCO 2024 ocean floor with viridis colormap
• Population at a Glance — proportional-symbol populated places, sized by population
• GDP per Capita PPP 2023 — country choropleth from World Bank Open Data
• The World’s Disputed Places — every disputed area Natural Earth tracks
• One Territory, Multiple Official Maps — Kashmir as China, India, and Pakistan see it
• Conflict Events 2024 — UCDP Georeferenced Event Dataset
• Refugees by Country of Origin 2023 — UNHCR statistics joined to country polygons

All data is bundled at image build time — no outbound network calls at runtime. The demo can be reset every 24 hours by the included reset service. To force a full reset:

docker compose -f docker-compose.yml -f docker-compose.demo.yml exec reset /scripts/reset-demo.sh
docker compose -f docker-compose.yml -f docker-compose.demo.yml restart seeder

Source attribution and licenses for every demo dataset are documented on each dataset’s detail page. All bundled data is CC-BY 4.0, ODbL 1.0, or Public Domain.

Next steps

• Going to production? See the Install Guide for full prerequisites, Docker Compose 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.