# 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 files, a shorthand for serving a directory of files.

• 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.adapters.files:DirectoryAdapter.from_directory
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: tiled.adapters.files:DirectoryAdapter.from_directory
args:
directory: "path/to/files"


### 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"


## 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.authenticator¶

Type of Authenticator to use.

These are typically from the tiled.authenticators module, though user-defined ones may be used as well.

This is given as an import path. In an import path, packages/modules are separated by dots, and the object itself it separated by a colon.

Example:

authenticator: tiled.examples.DummyAuthenticator


### authentication.args¶

Named arguments to pass to Authenticator. If there are none, args may be omitted or empty.

Example:

authenticator: tiled.examples.PAMAuthenticator
args:
service: "custom_service"


### 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.

## 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"


## 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.

## 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.

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 false. If enabled PROMETHEUS_MULTIPROC_DIR environment variable must be set to the path of a writable directory.