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

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.

expose_raw_assets

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