Installation Guide

This guide walks you through setting up the STAC GIS (STACGIS) platform in both production and development modes.

⚠️ The backend runs in Docker — and only in Docker. The backend depends on GDAL (via the gdal package plus rasterio, rio-tiler, rio-cogeo, and fiona), which requires native system libraries that are painful to install by hand. Both the dev and production images install their own Python runtime and GDAL, so there is no supported local (uv/uvicorn) backend setup. Docker is therefore a hard requirement, not an optional convenience.

The stack is made up of three moving parts:

Component	Location	Tech
Backend API	`backend/stacgis/`	FastAPI · PostgreSQL · Redis · Celery · GDAL
Frontend	`frontend/`	React · Vite · pnpm workspaces (Turbo)
Auxiliary services	—	PostgreSQL · Redis · MinIO (S3)

All relative paths below assume you start from the repository root (core/).

Prerequisites

Before you begin, make sure the following tools are installed on your machine:

Dependency	Version	Purpose
Node.js	`v20.0.0+`	JavaScript runtime for the frontend
pnpm	`v8.0.0+`	Fast, disk-space efficient package manager
Docker	`20.10.0+`	Required — runs the entire backend (API, worker, DB, Redis, MinIO)
Docker Compose	`v2.0.0+`	Orchestrating container services

💡 Tip: pnpm can be installed with npm install -g pnpm.

ℹ️ You do not need to install Python or uv locally. The backend dev and production images (Dockerfile.dev / Dockerfile) install their own Python runtime, GDAL, and all dependencies inside the image.

🐋 Production Setup

For production, run the entire stack as Docker containers using the root-level compose file. This includes an Nginx-based web gateway that serves the pre-built frontend and reverse-proxies /api to the backend, plus the database, cache, and object storage.

Because the backend requires GDAL, it is always built from the backend production image (backend/stacgis/Dockerfile) — there is no local uv/uvicorn path for production.

1. Configure environment variables

The API service reads its configuration from backend/stacgis/.env. Create and harden it for production:

cd backend/stacgis
cp .env.example .env

Key values to change for production:

ENVIRONMENT=production
DEBUG=false
SECRET_KEY — set a strong secret (e.g. openssl rand -hex 32)
DATABASE_URL, S3_*, REDIS_URL, CELERY_* — point at your persistent endpoints
CORS_ORIGINS — restrict to your real frontend origin

2. Build and start the stack

From the repository root (core/):

docker-compose up -d --build

The root compose file starts:

Service	Role
web	Nginx web gateway — serves the frontend and proxies `/api` to the backend
api	FastAPI application (production settings)
migrate	One-shot job that runs `alembic upgrade head`
worker	Celery worker for background tasks
db	PostgreSQL
redis	Redis cache & broker
minio	S3-compatible object storage

The migrate service automatically applies database migrations once the database is healthy, so there is no need to run Alembic by hand.

3. Verify the services

docker-compose ps
docker-compose logs -f api   # follow backend logs

Frontend: http://localhost (port 80)
API docs (if enabled): http://localhost/api/v1/docs

4. Backend-only production compose (API + workers)

If you are deploying the backend to a host or cluster that already provides its own frontend/gateway, use the dedicated backend-only compose file (still fully Docker-based — no local uv/uvicorn):

cd backend/stacgis
# Point DATABASE_URL, REDIS_URL, CELERY_*, SECRET_KEY, POSTGRES_*, REDIS_PASSWORD at real endpoints
cp .env.example .env
docker-compose -f docker-compose.prod.yml up -d --build

This starts api (3 replicas), celery_worker (2 replicas), celery_beat, db and redis from the same production image, plus an optional nginx reverse proxy. Unlike the root compose file there is no one-shot migrate service, so apply migrations once the database is healthy:

docker-compose -f docker-compose.prod.yml run --rm api alembic upgrade head

🛠️ Development Setup

For day-to-day development, the backend is always run in Docker (it needs GDAL, which can't be installed locally). Only the frontend runs on your host with hot-reload, while the backend API, Celery worker, and the database, Redis, and MinIO all run as Docker containers via the backend dev compose file.

⚠️ There is no supported local uv/uvicorn backend setup. The dev image (Dockerfile.dev) already bundles Python, GDAL, and every dependency, and your source is bind-mounted into the containers for hot-reload.

1. Backend (`backend/stacgis/`)

1.1 Configure environment variables

cd backend/stacgis
cp .env.example .env

Review .env and adjust SECRET_KEY, database, S3, and Redis values if they differ from the defaults. The MinIO service also reads its credentials from this file.

1.2 Build and start the backend stack in Docker

cd backend/stacgis
docker-compose up -d --build

This brings up:

api — FastAPI dev server on http://localhost:8000 (source is bind-mounted for hot-reload)
worker — Celery worker for background tasks
db — PostgreSQL — localhost:5432 (user postgres / postgres, db stacgis)
redis — broker/result backend
minio — API on http://localhost:9000, console on http://localhost:9001

Because your code is bind-mounted into the api and worker containers, code edits are picked up automatically (the dev image runs uvicorn with --reload) — no rebuild is needed when you change the source.

1.3 Run migrations and seed data

The dev compose has no one-shot migration service, so run Alembic inside the API container:

cd backend/stacgis
docker-compose run --rm api alembic upgrade head
docker-compose run --rm api python scripts/seed_data.py   # optional: seed initial demo data

1.4 Verify the backend

Backend API: http://localhost:8000
Interactive docs (Swagger): http://localhost:8000/docs

2. Frontend (`frontend/`)

The frontend is a pnpm workspace (managed by Turbo) that includes the main STACGIS app plus shared @packages/* libraries.

cd frontend
pnpm install
pnpm dev

STACGIS app is served at http://localhost:5000 (Vite dev server).
The Vite dev server proxies all /api/* requests to the backend at http://localhost:8000, so as long as the backend api container is running the app is fully functional.

3. Verify the full local stack

Service	URL
Frontend (STACGIS)	http://localhost:5000
Backend API	http://localhost:8000
Swagger docs	http://localhost:8000/docs
MinIO console	http://localhost:9001

To stop the backend containers when you're done:

cd backend/stacgis
docker-compose down

Troubleshooting

Symptom	Fix
Backend image fails to build (GDAL)	The build compiles `fiona`/`rasterio` against `libgdal-dev`; give Docker enough memory/RAM and retry `docker-compose up -d --build`
Backend can't connect to the database	Confirm `db`, `redis`, `minio` are running: `docker-compose ps`
Frontend API calls failing	Confirm the `api` container is up on `http://localhost:8000`: `docker-compose ps`
Stale migrations	Re-run `docker-compose run --rm api alembic upgrade head`

Prerequisites​

🐋 Production Setup

1. Configure environment variables​

2. Build and start the stack​

3. Verify the services​

4. Backend-only production compose (API + workers)​

🛠️ Development Setup

1. Backend (backend/stacgis/)​

1.1 Configure environment variables​

1.2 Build and start the backend stack in Docker​

1.3 Run migrations and seed data​

1.4 Verify the backend​

2. Frontend (frontend/)​

3. Verify the full local stack​

Troubleshooting​