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