Skip to main content

Quickstart: Run GeoLens locally in 10 minutes

Follow these steps to go from git clone to a fully operational GeoLens instance with admin access and your first uploaded dataset. No cloud accounts required - everything runs locally via Docker Compose.

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: Get the code

Fastest path — clone and install in one command:

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

Or get the code manually — clone the GeoLens repository or download the latest release tarball.

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

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

Step 2: Run the installer

scripts/install.sh copies .env.example to .env, generates a JWT signing secret, prompts for admin credentials (defaults to admin / admin), and runs docker compose up -d. Re-running it is idempotent - existing values are preserved. The first build downloads Postgres + PostGIS base images (~1 GB) and takes 5-10 minutes; subsequent starts are near-instant.

bash scripts/install.sh
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 credentials you set during install (default admin / admin):

  • Username: admin
  • Password: admin

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 the upload button in the catalog header, select the ZIP file, and confirm the detected CRS (EPSG:4326). Click Commit to publish. The dataset will appear in the catalog and be available through the OGC API at http://localhost:8001/collections.

What you'll see

After Step 5, your browser shows the GeoLens catalog with your first dataset. The map preview, metadata panel, and OGC API endpoints at http://localhost:8001/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.

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 - The first docker compose up builds images and downloads ~1 GB of base layers. Watch progress with docker compose logs -f. Subsequent starts are near-instant.
  • File upload fails - Confirm the file is one of the supported formats: GeoJSON, Shapefile ZIP, GeoPackage, CSV, or a public OGC service URL. Check the upload dialog for validation errors.

Next steps