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
tocubic
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_PROVIDER:
Optional
[str
]¶ Driver provider to use (sqlite, sqlite-remote, mysql, postgresql; auto-detected by default)
-
LAZY_LOADING_MAX_SHAPE:
Tuple
[int
,int
]¶ Maximum size to use when lazy loading metadata (less is faster but less accurate)
-
REMOTE_DB_CACHE_DIR:
str
¶ Path where cached remote SQLite databases are stored (when using sqlite-remote provider)
-
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)
-
DRIVER_PROVIDER:
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).