Configuration

Most information about the data served by a Terracotta instance is contained in the raster database. However, there are some runtime settings that apply to the Terracotta instance as a whole.

Because Terracotta can either run locally, on a web server, or serverless, you can configure these settings in several different ways:

  • Terracotta is fully configurable through environment variables that are prefixed with TC_. E.g., running

    $ export TC_RESAMPLING_METHOD=cubic

    will set the corresponding setting RESAMPLING_METHOD to cubic in all Terracotta instances. This is particularly useful for serverless deployments. You can set list values in JSON array notation:

    $ export TC_DEFAULT_TILE_SIZE="[128,128]"

  • All CLI commands accept the path to a TOML file via the -c flag. Example:

    $ terracotta -c config.toml serve -d tc.sqlite

    where config.toml contains e.g.

    DRIVER_PATH = root:password@myserver.com/terracotta
DRIVER_PROVIDER = mysql

  • If you are using the Terracotta Python API, you can call update_settings() directly.

Note

If you update a runtime setting while Terracotta is already running, your changes will not take effect until update_settings() is called. In other words, you might have to restart your Terracotta server for your changes to take effect.

Available runtime settings

All runtime settings are contained in the following NamedTuple.

See also

To see the types and default values of the settings, have a look at the TerracottaSettings source code.

class terracotta.config.TerracottaSettings(DRIVER_PATH: str = '', DRIVER_PROVIDER: str | None = None, DEBUG: bool = False, FLASK_PROFILE: bool = False, XRAY_PROFILE: bool = False, LOGLEVEL: str = 'warning', RASTER_CACHE_SIZE: int = 513802240, RASTER_CACHE_COMPRESS_LEVEL: int = 9, DEFAULT_TILE_SIZE: Tuple[int, int] = (256, 256), LAZY_LOADING_MAX_SHAPE: Tuple[int, int] = (1024, 1024), PNG_COMPRESS_LEVEL: int = 1, DB_CONNECTION_TIMEOUT: int = 10, REMOTE_DB_CACHE_DIR: str = '/tmp/terracotta', REMOTE_DB_CACHE_TTL: int = 600, RESAMPLING_METHOD: str = 'average', REPROJECTION_METHOD: str = 'linear', ALLOWED_ORIGINS_METADATA: List[str] = ['*'], ALLOWED_ORIGINS_TILES: List[str] = ['http[s]?://(localhost|127\\.0\\.0\\.1):*'], SQL_USER: str | None = None, SQL_PASSWORD: str | None = None, MYSQL_USER: str | None = None, MYSQL_PASSWORD: str | None = None, POSTGRESQL_USER: str | None = None, POSTGRESQL_PASSWORD: str | None = None, USE_MULTIPROCESSING: bool = True, MAX_POST_METADATA_KEYS: int = 100)[source]

Contains all settings for the current Terracotta instance.

DRIVER_PATH: str

Path to database

DRIVER_PROVIDER: Optional[str]

Driver provider to use (sqlite, sqlite-remote, mysql, postgresql; auto-detected by default)

DEBUG: bool

Activate debug mode in Flask app

FLASK_PROFILE: bool

Print profile information after every request

XRAY_PROFILE: bool

Send performance traces to AWS X-Ray

LOGLEVEL: str

Default log level (debug, info, warning, error, critical)

RASTER_CACHE_SIZE: int

Size of raster file in-memory cache in bytes

RASTER_CACHE_COMPRESS_LEVEL: int

Compression level of raster file in-memory cache, from 0-9

DEFAULT_TILE_SIZE: Tuple[int, int]

Tile size to return if not given in parameters

LAZY_LOADING_MAX_SHAPE: Tuple[int, int]

Maximum size to use when lazy loading metadata (less is faster but less accurate)

PNG_COMPRESS_LEVEL: int

Compression level of output PNGs, from 0-9

DB_CONNECTION_TIMEOUT: int

Timeout in seconds for database connections

REMOTE_DB_CACHE_DIR: str

Path where cached remote SQLite databases are stored (when using sqlite-remote provider)

REMOTE_DB_CACHE_TTL: int

Time-to-live of remote database cache in seconds

RESAMPLING_METHOD: str

Resampling method to use when reading reprojected data

REPROJECTION_METHOD: str

Resampling method to use when reprojecting data to Web Mercator

ALLOWED_ORIGINS_METADATA: List[str]

CORS allowed origins for metadata endpoint

ALLOWED_ORIGINS_TILES: List[str]

CORS allowed origins for tiles endpoints

SQL_USER: Optional[str]

SQL database username (if not given in driver path)

SQL_PASSWORD: Optional[str]

SQL database password (if not given in driver path)

MYSQL_USER: Optional[str]

Deprecated, use SQL_USER. MySQL database username (if not given in driver path)

MYSQL_PASSWORD: Optional[str]

Deprecated, use SQL_PASSWORD. MySQL database password (if not given in driver path)

POSTGRESQL_USER: Optional[str]

Deprecated, use SQL_USER. PostgreSQL database username (if not given in driver path)

POSTGRESQL_PASSWORD: Optional[str]

Deprecated, use SQL_PASSWORD. PostgreSQL database password (if not given in driver path)

USE_MULTIPROCESSING: bool

Use a process pool for band retrieval in parallel

MAX_POST_METADATA_KEYS: int

Maximum number of metadata keys per POST /metadata request

Cross-origin resource sharing (CORS)

Your application might need Terracotta to allow CORS for some or all hostnames. For example, this is required when using Mapbox GL to serve tiles (but generally depends on how the frontend requests resources from Terracotta).

You can control the CORS settings for the metadata (/metadata) and tiles (/rgb and /singleband) endpoints individually with the settings ALLOWED_ORIGINS_METADATA and ALLOWED_ORIGINS_TILES:

$ export TC_ALLOWED_ORIGINS_METADATA='["*"]'
$ export TC_ALLOWED_ORIGINS_TILES="[]"

The above settings are the defaults when you omit these settings (allow all origins for metadata, and no origins for tiles).