Install Guide

Step-by-step reference for deploying GeoLens from scratch using Docker Compose.

Prerequisites

Requirement	Minimum	Notes
Docker Engine	24.0+	Install Docker
Docker Compose	v2.20+	Included with Docker Desktop; standalone install via `docker compose --version`
Ports	3 ports	Default: 8080 (Frontend), 5434 (PostgreSQL), 8001 (API)

First install

Use the public installer for a first run:

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

Open http://localhost:8080 when the installer finishes. OGC API clients should connect through the reverse-proxy path at http://localhost:8080/api/.

First login: the admin username defaults to admin. A piped curl … | sh launched from your terminal still prompts for the admin password — the installer reads /dev/tty, not stdin. Only when there is no controlling terminal (CI, nohup, systemd) does it skip the prompt and auto-generate a strong admin password, storing it in the install directory’s .env (never printed to your terminal). The installer clones into geolens/ under the directory where you ran it (override with GEOLENS_INSTALL_DIR), so retrieve the password with:

grep '^GEOLENS_ADMIN_PASSWORD=' geolens/.env

From inside a source checkout (bash scripts/install.sh) the file is just .env rather than geolens/.env, and leaving the password prompt blank generates one the same way.

If you are installing from a source checkout instead:

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

Default services

docker compose up -d starts the frontend, API, worker, TiTiler, PostgreSQL, and the backup service, after a one-shot migrate job applies database migrations and exits. Automated backups run by default and write to the backup_data volume. Set BACKUP_S3_ENABLED=true and configure the standard S3_* variables to also push backups to off-site storage. See Configuration Reference: Backup for the full variable list.

Optional services (Docker Compose profiles)

GeoLens ships with a local development profile for S3-compatible storage and shared cache testing. These services are not started by docker compose up -d unless you opt in.

Profile	Services	When to use
`cloud-dev`	`minio`, `minio-setup`, `valkey`	Local S3-compatible object storage and Valkey cache for testing provider-style setups without provisioning real infrastructure

Run a local cloud-equivalent stack

docker compose --profile cloud-dev up -d

This starts MinIO (S3-compatible storage — the S3 API is on http://localhost:9000 and the web console on http://localhost:9001) and Valkey (Redis-compatible cache). To switch GeoLens to use them, uncomment the MinIO block in your .env (the settings are documented under “Local S3 Testing” in .env.example) and set REDIS_URL=redis://valkey:6379/0. MinIO has no default credentials: you must set MINIO_ROOT_USER and MINIO_ROOT_PASSWORD in your .env before starting this profile (generate them with openssl rand -base64 24). If either value is blank, the minio container refuses to start and exits with a fatal error. It will not fall back to any default account. Use this profile to develop or debug code paths that depend on S3 or shared cache without provisioning real cloud resources.

Stopping and starting

Stop all services (preserves data)

docker compose down

Start services

docker compose up -d

Stop and remove all data

docker compose down -v

The -v flag removes all project volumes — including pgdata, upload_staging, and backup_data — deleting all database data, uploaded files, and any local backups.

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api
docker compose logs -f db

Upgrading

For version upgrade procedures, rollback steps, and version-specific notes, see the Upgrade Guide.

Data persistence

Data is stored in two Docker volumes:

Volume	Purpose	Path inside container	Profile
`pgdata`	PostgreSQL data directory	`/var/lib/postgresql/data`	default
`upload_staging`	Uploaded files awaiting ingestion	`/app/staging`	default
`backup_data`	Automated database dumps from the `backup` service	`/backups`	default
`minio_data`	Local S3 object store for `cloud-dev` profile	`/data`	`cloud-dev`
`valkey_data`	Local Valkey cache state for `cloud-dev` profile	`/data`	`cloud-dev`

These volumes persist across docker compose down (without -v). See Admin Guide for backup procedures.

Troubleshooting

Missing or incomplete `.env` file

If you see a ValidationError with “Field required” errors on startup:

pydantic_core._pydantic_core.ValidationError: 3 validation errors for Settings

…or JWT_SECRET_KEY must be at least 32 characters, you either skipped creating .env or copied .env.example without filling in the required values (JWT_SECRET_KEY, GEOLENS_ADMIN_USERNAME, GEOLENS_ADMIN_PASSWORD all ship empty). The fastest fix is to run the installer, which generates a JWT secret and prompts for admin credentials (or auto-generates them when run non-interactively — see “First login” above):

bash scripts/install.sh

The script is idempotent; it only fills in missing values, so it’s safe to re-run on a partially-configured .env.

Migration warnings on startup

You may see log messages like:

INFO: Migrations already applied by migrate service (or database not ready yet)

This is expected and harmless. The dedicated migrate service runs Alembic migrations before the API starts. The API and worker entrypoints also attempt migrations as a safety net. When the migrate service has already applied them, the entrypoint logs this informational message and proceeds normally.

Port conflicts

If a port is already in use, change it in .env:

FRONTEND_PORT=8081
API_PORT=8002
DB_PORT=5435

Then restart:

docker compose down && docker compose up -d

Out of memory

If the database or API crashes with OOM errors:

Increase Docker memory allocation (Docker Desktop: Settings > Resources > Memory)
Reduce concurrent workloads (pause large ingests, narrow query bbox)

Services not starting

Check the startup order and health:

# View startup logs
docker compose logs --tail=50 db
docker compose logs --tail=50 api

# Check health status
docker compose ps

Common issues:

db not healthy: Check POSTGRES_USER and POSTGRES_PASSWORD match in .env
api not starting: Verify database is healthy first; check migration errors in API logs
frontend 502 errors: Upstream API not ready yet; wait 30 seconds and retry

Export 500 errors (staging permission denied)

If /api/datasets/{id}/export returns HTTP 500, verify staging writability inside the API container:

docker compose exec api sh -lc '\
  dir=${UPLOAD_STAGING_DIR:-/app/staging}; \
  mkdir -p "$dir/exports" && \
  touch "$dir/.geolens-write-test" "$dir/exports/.geolens-write-test" && \
  rm -f "$dir/.geolens-write-test" "$dir/exports/.geolens-write-test"'

Run the runtime export verification spec after permissions are corrected:

npm run e2e -- e2e/export-runtime.spec.ts

Expected success signals:

Exports pass for gpkg, geojson, shp, and csv with attachment payload integrity (SQLite header, FeatureCollection JSON, zip members, CSV header row).
target_crs=EPSG:3857 export confirms projected coordinate semantics as well as HTTP 200.
bbox and where exports are true subsets (feature/property assertions pass).
Audit logs include dataset.export entries with export parameters.

If the writability check fails:

Fix ownership/permissions on the mounted staging path so uid:gid 1001:1001 can write.
Or set UPLOAD_STAGING_DIR in .env to a writable directory and restart services with docker compose up -d --build.
Re-run npm run e2e -- e2e/export-runtime.spec.ts to confirm full runtime behavior.

GDAL/OGR errors during ingestion

The API container includes GDAL. If file ingestion fails:

# Check API logs for OGR errors
docker compose logs api | grep -i "ogr\|gdal\|error"

Supported upload formats (the UPLOAD_ALLOWED_EXTENSIONS default, which admins can narrow in Admin → Storage): .zip (Shapefile), .gpkg (GeoPackage), .geojson, .json, .csv, .tif/.tiff (GeoTIFF/COG), .parquet (GeoParquet), and .xlsx/.xls (Excel). See Configuration Reference → Upload settings.

Database connection errors

Verify the database is accessible:

docker compose exec db pg_isready -U geolens -d geolens

If the database is unreachable from the API, ensure the POSTGRES_HOST is set to db (the Docker service name).

Reset to clean state

To completely reset the installation:

docker compose down -v
docker compose up -d

This removes all data and starts fresh with the default admin account.