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 same path 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 for tiled.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.init_if_not_exists

Initialize authentication database tables if database is empty.

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

DEPRECATED. The object cache has been removed. This configuration no longer has any effect.

object_cache.available_bytes

DEPRECATED. The object cache has been removed. This configuration no longer has any effect.

object_cache.log_level

DEPRECATED. The object cache has been removed. This configuration no longer has any effect.

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.

expose_raw_assets

If true (default), enable clients to download the raw asset data that backs nodes that they are authorized to read.