Configuration

stac-catalog is configured three ways. Precedence (highest → lowest):

CLI options  >  configuration file  >  built-in defaults

Environment variables override the database connection settings (see below).

Configuration file

Copy the example to create your own:

cp stac-config.example.yaml stac-config.yaml

A full config looks like:

default_source: csv

sources:
  csv:
    input: ./input # folder containing collections.csv (+ optional tables)

  gsheet:
    spreadsheet_id: YOUR_SHEET_ID
    credentials: ./credentials.json # Google service-account JSON

output: ./output # where STAC JSON is written

Keys

Key	Description
default_source	Metadata source: csv or gsheet. Can be overridden per command with --source.
sources.csv.input	Directory containing collections.csv (and optional providers.csv, catalogs.csv).
sources.gsheet.spreadsheet_id	The Google Spreadsheet ID.
sources.gsheet.credentials	Path to the Google service-account credentials JSON.
output	Directory where catalogs.json, providers.json, collections.json, and items.ndjson are written.

Path resolution

Relative paths in the config file are resolved relative to the directory that contains the config file (not the working directory). So you can keep a single config in one place and point it at sibling folders.

:::tip Keeping secrets out of the config default_source, sources, and output are fine to commit (with placeholder values). Google Sheets credentials and the .env database password are secrets - keep them private and never commit them. :::

Built-in defaults

With no config file, these defaults are used (from stac_catalog/config.py):

Key	Default
default_source	csv
sources.csv.input	./input
output	./output
database.host	localhost
database.port	5432
database.name	stac
database.user	postgres

Database connection (environment)

The load command builds a PostgreSQL DSN in this order (first match wins):

1. --dsn CLI option
2. PGSTAC_DSN environment variable
3. POSTGRES_HOST / POSTGRES_PORT / POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD environment variables
4. The database section of the config / built-in defaults

POSTGRES_PASSWORD is required for host-side load. Example:

export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=stac
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=stac

:::note --prod ignores --dsn With --prod the database is reached inside the private Docker network, so you must not pass --dsn (and not --input/--output). See CLI reference. :::

TiTiler URLs

Two TiTiler URLs are used when generating STAC assets:

Setting	Meaning
internal TiTiler URL	Address the generator uses to call TiTiler (e.g. http://titiler:8000 inside the network).
public TiTiler URL	Address written into the STAC assets so end users can load tiles/thumbnails (e.g. https://tiles.example.org).

They are configured on the generator service in docker-compose.yml:

environment:
  TITILER_URL: http://titiler:8000 # internal
  TITILER_PUBLIC_URL: https://tiles.example.org # public

You can override both per command with --titiler-url and --titiler-public-url (see CLI reference).

Google Sheets configuration

To use a Google Sheet as the metadata source:

default_source: gsheet

sources:
  gsheet:
    spreadsheet_id: YOUR_SHEET_ID
    credentials: ./credentials.json

output: ./output

Then run with the source selected:

stac-catalog sync --source gsheet --config stac-config.yaml

Google Sheets uses tabs named collections, providers, and catalogs - the same logical tables as the CSV files (see Metadata).