Configuration

FastGIS is configured through environment variables (.env file or shell environment at deploy time).

Core variables

Variable	Required	Default	Description
SECRET_KEY	✅	—	Session signing key (random 32+ chars)
GRASS_GISDBASE	✅	—	Absolute path to the GRASS database directory
MAPSERVER_URL	✅	—	Base URL of the MapServer instance
REDIS_URL	❌	redis://localhost:6379	Redis connection string
ADMIN_API_KEY	❌	—	Bootstrap admin API key on first startup
ADMIN_USERNAME	❌	—	Bootstrap admin web user on first startup
ADMIN_PASSWORD	❌	—	Bootstrap admin password
ADMIN_EMAIL	❌	—	Bootstrap admin email
APP_BASE_URL	❌	—	Public base URL (used in share links)
ALLOWED_ORIGINS	❌	*	Comma-separated CORS allowed origins
MAX_CONCURRENT_TASKS	❌	4	Maximum simultaneously running GRASS tasks
TASK_TIMEOUT_SECONDS	❌	600	Kill a task after this many seconds
DATA_ROOT	❌	/data	Root directory for all on-disk data (curvature DB, tiles, support data, …)

GRASS vector attribute backend

Variable	Required	Default	Description
GRASS_DB_DEFAULT_DRIVER	❌	sqlite	Default vector attribute backend (sqlite or pg)
POSTGRES_HOST	❌	—	PostgreSQL/PostGIS host
POSTGRES_PORT	❌	5432	PostgreSQL port
POSTGRES_DB	❌	—	PostgreSQL database name
POSTGRES_USER	❌	—	PostgreSQL user
POSTGRES_PASSWORD	❌	—	PostgreSQL password
POSTGRES_SCHEMA	❌	public	PostgreSQL schema for app-side DB tools

New environments can choose their vector attribute backend per create request. Setting GRASS_DB_DEFAULT_DRIVER=pg means new environments default to PostgreSQL. Existing environments keep their own db.connect state; changing the default only affects environments created afterward.

Valhalla routing

Variable	Required	Default	Description
VALHALLA_URL	❌	http://valhalla:8002	Internal URL of the Valhalla service
VALHALLA_USE_TILES_IGNORE_PBF	❌	False	Skip tile rebuild on container restart — set True after first build
VALHALLA_FORCE_REBUILD	❌	False	Force full tile rebuild on next restart
VALHALLA_BUILD_ELEVATION	❌	True	Include elevation data in tile build
VALHALLA_BUILD_ADMINS	❌	True	Build admin boundary database
VALHALLA_BUILD_TIME_ZONES	❌	True	Build timezone database
VALHALLA_SERVER_THREADS	❌	2	Threads for tile serving
OVERPASS_URL	❌	https://overpass-api.de/api/interpreter	Overpass API endpoint for speed cameras and POI

Curvature database

Variable	Required	Default	Description
CURVATURE_DB	❌	$DATA_ROOT/curvature/roads.db	Path to the curvature SQLite database
CURVATURE_THRESHOLD	❌	both	Fallback threshold if not specified per-request (300, 1000, or both). The rebuild API curvature_threshold field takes precedence over this env var.

Offline data tiles

Variable	Required	Default	Description
POI_TILE_DIR	❌	$DATA_ROOT/poi-tiles	Directory containing 1°×1° POI SQLite tiles
CURV_TILE_DIR	❌	$DATA_ROOT/curv-tiles	Directory containing 1°×1° curvature SQLite tiles
POI_BUNDLE_DIR	❌	$DATA_ROOT/poi-bundles	Directory for per-region monolithic POI bundles (legacy)
SUPPORT_DATA_DIR	❌	$DATA_ROOT/support_data	KMZ + WorldPop CSV files used by the curvature pipeline
REGIONS_YML	❌	/app/regions.yml	Path to the regions configuration file

Data pipeline control (startup skip flags)

Variable	Default	Description
FETCH_REGION_DATA	true	Set false to skip fetch_region_data.py on container start after first build
REBUILD_CURVATURE_DB	false	Set true to force a full curvature DB rebuild on next start

MapServer

FastGIS generates a Mapfile per GRASS environment on demand. The Mapfile is written to a directory read by MapServer. Ensure MapServer has read access to GRASS_GISDBASE and write access to the Mapfile output directory.

Redis

Named workspace sessions, routing cache, and field session metadata are stored in Redis. If Redis is unavailable:

• Session API returns 503 errors (autosave via localStorage still works)
• Routing speed-camera / POI caches are bypassed (live Overpass requests instead)
• Field session registry falls back to WFS-layer scanning on the mobile client

.env example

SECRET_KEY=change-me-to-a-random-32-char-string
GRASS_GISDBASE=/data/grassdb
MAPSERVER_URL=http://mapserver/cgi-bin/mapserv
REDIS_URL=redis://redis:6379/0
ALLOWED_ORIGINS=https://fastgis.example.com

# Vector attribute backend
GRASS_DB_DEFAULT_DRIVER=pg
POSTGRES_HOST=postgis
POSTGRES_PORT=5432
POSTGRES_DB=fastgis
POSTGRES_USER=fastgis
POSTGRES_PASSWORD=change-me
POSTGRES_SCHEMA=public

# Routing
VALHALLA_URL=http://valhalla:8002
VALHALLA_USE_TILES_IGNORE_PBF=True
OVERPASS_URL=https://overpass-api.de/api/interpreter

# Data root
DATA_ROOT=/data

# Offline data tiles
POI_TILE_DIR=/data/poi-tiles
CURV_TILE_DIR=/data/curv-tiles
SUPPORT_DATA_DIR=/data/support_data
REGIONS_YML=/app/regions.yml

# Skip startup rebuilds (set after first successful build)
FETCH_REGION_DATA=false
REBUILD_CURVATURE_DB=false