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: Optional[str] = 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] = [], MYSQL_USER: Optional[str] = None, MYSQL_PASSWORD: Optional[str] = None)[source]

Contains all settings for the current Terracotta instance.

property DRIVER_PATH

Path to database

property DRIVER_PROVIDER

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

property DEBUG

Activate debug mode in Flask app

property FLASK_PROFILE

Print profile information after every request

property XRAY_PROFILE

Send performance traces to AWS X-Ray

property LOGLEVEL

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

property RASTER_CACHE_SIZE

Size of raster file in-memory cache in bytes

property RASTER_CACHE_COMPRESS_LEVEL

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

property DEFAULT_TILE_SIZE

Tile size to return if not given in parameters

property LAZY_LOADING_MAX_SHAPE

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

property PNG_COMPRESS_LEVEL

Compression level of output PNGs, from 0-9

property DB_CONNECTION_TIMEOUT

Timeout in seconds for database connections

property REMOTE_DB_CACHE_DIR

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

property REMOTE_DB_CACHE_TTL

Time-to-live of remote database cache in seconds

property RESAMPLING_METHOD

Resampling method to use when reading reprojected data

property REPROJECTION_METHOD

Resampling method to use when reprojecting data to Web Mercator

property ALLOWED_ORIGINS_METADATA

CORS allowed origins for metadata endpoint

property ALLOWED_ORIGINS_TILES

CORS allowed origins for tiles endpoints

property MYSQL_USER

MySQL database username (if not given in driver path)

property MYSQL_PASSWORD

MySQL database password (if not given in driver path)

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).