--- orphan: true --- # Service Configuration Reference This is a comprehensive reference. See also {doc}`../how-to/configuration` 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. (schema_trees)= ## trees This section contains a *list* of one or more items, each describing a Tree to be served. (schema_trees.tree)= ### 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 (schema_trees.path)= ### trees[item].path URL subpath for to serve this Tree on. A good default choice is `"/"` if you are serving one Tree. (schema_trees.args)= ### 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: ```yaml - path: "/" tree: catalog args: uri: "catalog.db" ``` (schema_trees.access_control)= ### 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: ```yaml access_control: access_policy: "tiled.adapters.mapping:SimpleAccessPolicy" args: access_lists: alice: ["A", "B"] bob: ["C"] cara: "tiled.adapters.mapping:SimpleAccessPolicy.ALL" ``` (schema_trees.access_control.args)= #### trees.access_control.args (schema_trees.access_control.access_policy)= #### trees.access_control.access_policy (schema_media_types)= ## media_types (schema_media_types.array)= ### 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 ```yaml application/x-my-custom-format: package.module:exporter_function ``` (schema_media_types.dataframe)= ### 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 ```yaml application/x-my-custom-format: package.module:exporter_function ``` (schema_media_types.dataset)= ### 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 ```yaml application/x-my-custom-format: package.module:exporter_function ``` (schema_file_extensions)= ## 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 ``` (schema_authentication)= ## authentication This section describes whether and how to authenticate users. (schema_authentication.providers)= ### authentication.providers (schema_authentication.tiled_admins)= ### authentication.tiled_admins Give users with these identities 'admin' Role. (schema_authentication.tiled_admins.provider)= #### authentication.tiled_admins[item].provider (schema_authentication.tiled_admins.id)= #### authentication.tiled_admins[item].id (schema_authentication.secret_keys)= ### 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))" (schema_authentication.allow_anonymous_access)= ### 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. (schema_authentication.single_user_api_key)= ### 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))" (schema_authentication.access_token_max_age)= ### 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**. (schema_authentication.refresh_token_max_age)= ### authentication.refresh_token_max_age Time after which inactive sessions (sessions that have not refreshed tokens) will time out. Default is Units are **seconds**. (schema_authentication.session_max_age)= ### 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. (schema_database)= ## database (schema_database.uri)= ### 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. (schema_database.init_if_not_exists)= ### database.init_if_not_exists Initialize authentication database tables if database is empty. (schema_database.pool_pre_ping)= ### database.pool_pre_ping If true (default), use pessimistic connection testings. This is recommended. (schema_database.pool_size)= ### database.pool_size Connection pool size. Default is 5. Minimum is 2. (schema_database.max_overflow)= ### database.max_overflow Connection pool max overflow. Default is 5. (schema_access_control)= ## access_control This section describes which users can see which entries. (schema_access_control.access_policy)= ### 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: ```yaml access_control: access_policy: "tiled.adapters.mapping:SimpleAccessPolicy" args: access_lists: alice: ["A", "B"] bob: ["C"] cara: "tiled.adapters.mapping:SimpleAccessPolicy.ALL" ``` (schema_access_control.args)= ### access_control.args (schema_object_cache)= ## object_cache DEPRECATED. The object cache has been removed. This configuration no longer has any effect. (schema_object_cache.available_bytes)= ### object_cache.available_bytes DEPRECATED. The object cache has been removed. This configuration no longer has any effect. (schema_object_cache.log_level)= ### object_cache.log_level DEPRECATED. The object cache has been removed. This configuration no longer has any effect. (schema_response_bytesize_limit)= ## 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. (schema_allow_origins)= ## allow_origins This list of domains enables web apps served from other domains to make requests to the tiled serve. Example: ```yaml 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 (schema_uvicorn)= ## uvicorn (schema_uvicorn.host)= ### 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'`. (schema_uvicorn.port)= ### uvicorn.port Bind to a socket with this port. Default `8000`. (schema_uvicorn.workers)= ### uvicorn.workers Use multiple worker processes. Defaults to the `$WEB_CONCURRENCY` environment variable if available, or `1`. (schema_uvicorn.root_path)= ### uvicorn.root_path Configure the application with a root_path when it is behind a proxy serving it on some path prefix. (schema_uvicorn.proxy_headers)= ### 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. (schema_uvicorn.forwarded_allow_ips)= ### 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. (schema_uvicorn.ssl_keyfile)= ### uvicorn.ssl_keyfile SSL key file (schema_uvicorn.ssl_certfile)= ### uvicorn.ssl_certfile SSL certificate file (schema_uvicorn.ssl_keyfile_password)= ### uvicorn.ssl_keyfile_password SSL keyfile password (schema_uvicorn.ssl_version)= ### uvicorn.ssl_version SSL version to use (see stdlib ssl module's). Default 2. (schema_uvicorn.ssl_cert_reqs)= ### uvicorn.ssl_cert_reqs Whether client certificate is required (see stdlib ssl module's). Default 0. (schema_uvicorn.ssl_ca_certs)= ### uvicorn.ssl_ca_certs CA certificates file (schema_uvicorn.ssl_ciphers)= ### uvicorn.ssl_ciphers Ciphers to use (see stdlib ssl module's). Default TLSv1. (schema_metrics)= ## metrics (schema_metrics.prometheus)= ### metrics.prometheus Enable/disable prometheus metrics. Default is true. (schema_specs)= ## specs List of specs accepted for uploaded data, with optional validation. Given as a spec with an importable function, as in ```yaml - spec: my-spec validator: package.module:validator_function ``` The validation function should have signature ```python 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. (schema_specs.spec)= ### specs[item].spec (schema_specs.validator)= ### specs[item].validator (schema_reject_undeclared_specs)= ## 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. (schema_expose_raw_assets)= ## expose_raw_assets If true (default), enable clients to download the raw asset data that backs nodes that they are authorized to read.