Service Configuration Reference¶
This is a comprehensive reference. See also Serve Data using Configuration Files for a practical guide with examples.
Configuration merging rules¶
If there are multiple configuration files:
At most one may contain an
authentication:
section.More than one may contain a
tree:
section, but if the samepath
occurs in more than one file, or if colliding paths like/a
and/a/b
are specified, an exception will be raised.If there is more than one
allow_origins
section their contents are merged.The behavior of other top-level collisions are currently undefined and will likely be made strict in the future.
The content below is automatically generated from a schema that is used to validate configuration files when they are read.
Environment variable expansion¶
Any values with environment variables, given as $VAR
or ${VAR}
, will be
expanded (i.e. filled in) with their values.
trees¶
This section contains a list of one or more items, each describing a Tree to be served.
trees[item].tree¶
Type of tree to serve. This may be:
The string
catalog
, a shorthand fortiled.catalog:from_uri
An import path to a Tree instance.
An import path to a callable (function or type) that returns a Tree. For these, the
args:
parameter below must be used as well.
In an import path, packages/modules are separated by dots, and the object itself it separated by a colon.
Examples:
# Tree instances
tiled.examples.generated_minimal:tree
tiled examples.generated:tree
my_python_module:my_tree_instance
# Callables that return Tree instances
tiled.catalog:from_uri
my_python_module:CustomTree
trees[item].path¶
URL subpath for to serve this Tree on.
A good default choice is "/"
if you are serving
one Tree.
trees[item].args¶
If tree:
is set to files
or some callable that returns a
Tree, this parameter must be included. It may contain named
arguments to pass to the callable. It may be empty or null
if the
callable requires no arguments.
Example:
- path: "/"
tree: catalog
args:
uri: "catalog.db"
trees[item].access_control¶
AccessPolicy object encoding rules for which users can see which entries. If this is set (not null) then an authenticator must also be set.
Example:
access_control:
access_policy: "tiled.adapters.mapping:SimpleAccessPolicy"
args:
access_lists:
alice: ["A", "B"]
bob: ["C"]
cara: "tiled.adapters.mapping:SimpleAccessPolicy.ALL"
trees.access_control.args¶
trees.access_control.access_policy¶
media_types¶
media_types.array¶
Additional exporters (a.k.a. serializers) for array structures.
Given as a media type (a.k.a MIME type) mapped to an importable function, as in
application/x-my-custom-format: package.module:exporter_function
media_types.dataframe¶
Additional exporters (a.k.a. serializers) for dataframe structures.
Given as a media type (a.k.a MIME type) mapped to an importable function, as in
application/x-my-custom-format: package.module:exporter_function
media_types.dataset¶
Additional exporters (a.k.a. serializers) for xarray dataset structures.
Given as a media type (a.k.a MIME type) mapped to an importable function, as in
application/x-my-custom-format: package.module:exporter_function
file_extensions¶
This supports the convenience alias ?format=ext
to request a format
corresponding to some file extension ext
.
Contents should map file extension to a media type (a.k.a MIME type) as in
ext: application/x-my-custom-format
authentication¶
This section describes whether and how to authenticate users.
authentication.providers¶
authentication.tiled_admins¶
Give users with these identities ‘admin’ Role.
authentication.tiled_admins[item].provider¶
authentication.tiled_admins[item].id¶
authentication.secret_keys¶
Secret keys used to sign secure tokens.
When generating a secret, is important to produce a difficult-to-guess random number, and make it different each time you start up a server. Two equally good ways to generate a secure secret…
With openssl
:
openssl rand -hex 32
With python
:
python -c "import secrets; print(secrets.token_hex(32))"
authentication.allow_anonymous_access¶
If true, allow unauthenticated, public access to any entries that are not specifically controlled with an access policy.
Default is false.
authentication.single_user_api_key¶
Secret API key used in single-user deployments.
When generating a secret, is important to produce a difficult-to-guess random number, and make it different each time you start up a server. Two equally good ways to generate a secure secret…
With openssl
:
openssl rand -hex 32
With python
:
python -c "import secrets; print(secrets.token_hex(32))"
authentication.access_token_max_age¶
This controls how often fresh access token have to be re-issued. The process is transparent to the user and just affects performance. An access token cannot be revoked, so its lifetime should be short. The default is 900 seconds (15 minutes).
Units are seconds.
authentication.refresh_token_max_age¶
Time after which inactive sessions (sessions that have not refreshed tokens) will time out. Default is
Units are seconds.
authentication.session_max_age¶
Even active sessions are timed out after this limit, and the user is required to resubmit credentials. By default, this is unset and active session are never shut down.
database¶
database.uri¶
When Tiled is configured with authentication providers, it uses a SQL database to persist information related to identities, sessions, and keys. (When it is used without authentication providers, no database is used.)
If Tiled is configured with authentication providers above but a database
URI is not specified, sqlite+aiosqlite:///./tiled.sqlite
(i.e. a SQLite database in
the current working directory) will be used.
Tiled officially supports PostgreSQL and SQLite, but any database engine supported by SQLAlchemy may work.
database.pool_pre_ping¶
If true (default), use pessimistic connection testings. This is recommended.
database.pool_size¶
Connection pool size. Default is 5. Minimum is 2.
database.max_overflow¶
Connection pool max overflow. Default is 5.
access_control¶
This section describes which users can see which entries.
access_control.access_policy¶
AccessPolicy object encoding rules for which users can see which entries. If this is set (not null) then an authenticator must also be set.
Example:
access_control:
access_policy: "tiled.adapters.mapping:SimpleAccessPolicy"
args:
access_lists:
alice: ["A", "B"]
bob: ["C"]
cara: "tiled.adapters.mapping:SimpleAccessPolicy.ALL"
access_control.args¶
object_cache¶
The ‘object’ cache is available to all Adapters to cache arbitrary objects, including file handles or chunks of data, in process memory.
object_cache.available_bytes¶
Maximum size for the object cache, given as a number of bytes as in 1_000_000 or as a fraction of system RAM (total physical memory) as in 0.3. Set to 0 to disable this cache. By default, it will use up to 0.15 (15%) of RAM.
object_cache.log_level¶
Set to “debug” level to log cache hits, misses, and stores. Default is “info” level, which logs cache configuration at application startup.
response_bytesize_limit¶
Maximum byte size of a response, given in bytes. The default is low (300 MB) keeping in mind that data is read into server memory and should generally be fetched in chunks.
allow_origins¶
This list of domains enables web apps served from other domains to make requests to the tiled serve.
Example:
allow_origins:
- https://chart-studio.plotly.com
Read more about Cross-Origin Resource Sharing (CORS) from Mozilla’s web developer documentation.
https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
uvicorn¶
uvicorn.host¶
Bind socket to this host. Use --host 0.0.0.0
to make the application
available on your local network. IPv6 addresses are supported, for
for example –host '::'
. Default '127.0.0.1'
.
uvicorn.port¶
Bind to a socket with this port. Default 8000
.
uvicorn.workers¶
Use multiple worker processes. Defaults to the $WEB_CONCURRENCY
environment variable if available, or 1
.
uvicorn.root_path¶
Configure the application with a root_path when it is behind a proxy serving it on some path prefix.
uvicorn.proxy_headers¶
Enable/Disable X-Forwarded-Proto, X-Forwarded-For, X-Forwarded-Port to populate remote address info. Defaults to enabled, but is restricted to only trusting connecting IPs in the forwarded-allow-ips configuration.
uvicorn.forwarded_allow_ips¶
Comma separated list of IPs to trust with proxy headers. Defaults to
the $FORWARDED_ALLOW_IPS
environment variable if available, or
‘127.0.0.1’. A wildcard ‘*’ means always trust.
uvicorn.ssl_keyfile¶
SSL key file
uvicorn.ssl_certfile¶
SSL certificate file
uvicorn.ssl_keyfile_password¶
SSL keyfile password
uvicorn.ssl_version¶
SSL version to use (see stdlib ssl module’s). Default 2.
uvicorn.ssl_cert_reqs¶
Whether client certificate is required (see stdlib ssl module’s). Default 0.
uvicorn.ssl_ca_certs¶
CA certificates file
uvicorn.ssl_ciphers¶
Ciphers to use (see stdlib ssl module’s). Default TLSv1.
metrics¶
metrics.prometheus¶
Enable/disable prometheus metrics. Default is true.
specs¶
List of specs accepted for uploaded data, with optional validation.
Given as a spec with an importable function, as in
- spec: my-spec
validator: package.module:validator_function
The validation function should have signature
f(metadata, structure_family, structure, spec)
and return None
or a possibly modified metadata object to indicate
success or raise a tiled.validation_registration.ValidationError
exception to indicate failure. If a metadata object is returned it
will be sent back to client in the response to the POST.
specs[item].spec¶
specs[item].validator¶
reject_undeclared_specs¶
If true, any data uploaded with a “spec” that is not declared in this configuration file will be rejected. By default, this is set to false —i.e., permissive.