Server configuration¶

A SimDB server reads its settings from an INI-style file named app.cfg in the application configuration directory. Find that directory with:

dirname "$(simdb config path)"

The file must have 0600 permissions (owner read/write only), because it contains secrets such as the admin password and Flask secret key.

This page is the reference for every app.cfg option. For task-oriented setup, see the Operating a server guides.

`[database]`¶

Option	Required	Description
`type`	Yes	Database type: `sqlite` or `postgres`.
`file`	If `type=sqlite`	SQLite database file. Defaults to `remote.db` in the user data directory.
`host`	If `type=postgres`	Database host.
`port`	If `type=postgres`	Database port.
`name`	If `type=postgres`	Database name.

See Set up PostgreSQL.

`[server]`¶

Option	Required	Description
`upload_folder`	Yes	Root directory where simulation files are stored.
`admin_password`	Yes	Password for the `admin` superuser.
`port`	No	Port the built-in server listens on. Defaults to 5000.
`ssl_enabled`	No	`True`/`False`: whether the built-in server uses SSL. Set `False` behind a dedicated web server. Defaults to `False`.
`ssl_cert_file`	If `ssl_enabled=True`	Path to the SSL certificate file.
`ssl_key_file`	If `ssl_enabled=True`	Path to the SSL key file.
`token_lifetime`	No	Days that generated tokens stay valid. Defaults to 30.
`imas_remote_host`	No	Host set on ingested IMAS URIs so data can be fetched via an IMAS remote access server. For example `imas:hdf5?path=foo` becomes `imas://<imas_remote_host>:<imas_remote_port>/uda?path=foo&backend=hdf5` on ingest.
`imas_remote_port`	No	Port set on ingested IMAS URIs. See `imas_remote_host`.

`[flask]`¶

Option	Required	Description
`secret_key`	Yes	Key used to sign server messages and authentication tokens. Use at least 20 characters.
`flask_env`	No	`development` or `production`. Defaults to `production`.
`debug`	No	`True`/`False`. Defaults to `True` when `flask_env=development`, otherwise `False`.
`testing`	No	`True`/`False`: propagate exceptions instead of handling them. Defaults to `False`.
`swagger_ui_doc_expansion`	No	Default Swagger UI state: `none`, `list`, or `full`.

`[validation]`¶

Option	Required	Description
`auto_validate`	No	`True`/`False`: run validation on uploaded simulations automatically. Defaults to `False`.
`error_on_fail`	No	`True`/`False`: reject simulations that fail validation. Requires `auto_validate=True`. Defaults to `False`.

`[file_validation]`¶

Options for validating the contents of simulation data files. Currently only the ids_validator is available. See Configure validation.

Option	Required	Description
`type`	No	Name of the file validator, for example `ids_validator`.
`extra_rule_dirs`	For `ids_validator`	Comma-separated directories containing extra rulesets.
`rulesets`	For `ids_validator`	Comma-separated ruleset names to apply.
`bundled_ruleset`	For `ids_validator`	`True`/`False`: load rulesets bundled with `ids_validator`. Defaults to `True`.
`apply_generic`	For `ids_validator`	`True`/`False`: apply generic rulesets. Defaults to `True`.
`rule_filter_name`	For `ids_validator`	Only apply rulesets whose names match these comma-separated values.
`rule_filter_ids`	For `ids_validator`	Only apply rulesets for these comma-separated IDS names.

`[email]`¶

Outgoing SMTP server used to send watcher notifications.

Option	Required	Description
`server`	Yes	SMTP server hostname.
`port`	Yes	SMTP server port.
`user`	Yes	SMTP user to send mail from.
`password`	Yes	SMTP user password.

`[authentication]`¶

Option	Required	Description
`type`	Yes	Authentication method: `ActiveDirectory`, `LDAP`, or `None`.
`firewall_auth`	No	`True`/`False`: read authentication from firewall headers (server runs behind a firewall).
`firewall_user`	If `firewall_auth=True`	Name of the firewall header carrying the username.
`firewall_email`	If `firewall_auth=True`	Name of the firewall header carrying the user’s email.

Active Directory (`type = ActiveDirectory`)¶

Option	Required	Description
`ad_server`	Yes	Active Directory server.
`ad_domain`	Yes	Active Directory domain.
`ad_cert`	No	Path to the root CA certificate.

LDAP (`type = LDAP`)¶

Option	Required	Description
`ldap_server`	Yes	LDAP server URI.
`ldap_bind`	Yes	Bind string. May contain `{username}`, for example `uid={username},ou=Users,dc=eufus,dc=eu`.
`ldap_query_base`	Yes	Search base, for example `dc=eufus,dc=eu`.
`ldap_query_filter`	Yes	Filter to find the user. May contain `{username}`, for example `(uid={username})`.
`ldap_query_user`	No	Bind user for queries. If omitted, queries run as the authenticated user.
`ldap_query_password`	No	Password for `ldap_query_user`. Required if `ldap_query_user` is set.
`ldap_query_uid`	No	Name of the user parameter in the search result. Defaults to `uid`.
`ldap_query_mail`	No	Name of the email parameter in the search result. Defaults to `mail`.

See Configure authentication.

`[cache]`¶

Option	Required	Description
`type`	No	`NullCache` (default), `SimpleCache`, or `FileSystemCache`.
`dir`	No	Directory for `FileSystemCache`.
`default_timeout`	No	Default cache timeout in seconds.
`threshold`	No	Maximum number of items before eviction (`SimpleCache`/`FileSystemCache`).

More options are available; take any setting from the Flask-Caching documentation, drop the CACHE_ prefix and lowercase it, for example CACHE_ARGS becomes args.

`[development]`¶

Option	Required	Description
`disable_checksum`	No	`True`/`False`: skip integrity checks. For testing only. Defaults to `False`.

`[celery]`¶

Used by the optional background workers in the Docker Compose deployment.

Option	Required	Description
`broker_url`	For workers	Message broker URL, for example `redis://redis:6379/0`.
`result_backend`	For workers	Result backend URL, for example `redis://redis:6379/0`.

`[partition]`¶

Option	Required	Description
`data`	No	Directory used for partitioned data, for example `/data/simdb/partition`.

`[role "NAME"]`¶

Defines a named role. Each role section needs a users option.

Option	Required	Description
`users`	Yes	Comma-separated list of usernames in this role.

Currently only the admin role is used: it grants access to the simdb remote admin subcommands.

[role "admin"]
users = admin,user1,user2

Example: SQLite server¶

[flask]
flask_env = development
debug = True
testing = True
secret_key = CHANGE_ME_TO_A_LONG_RANDOM_STRING

[server]
upload_folder = /tmp/simdb/simulations
ssl_enabled = False
admin_password = admin

[database]
type = sqlite

[validation]
auto_validate = True
error_on_fail = True

[email]
server = smtp.example.org
port = 465
user = simdb@example.org
password = CHANGE_ME

[authentication]
type = None

Example: PostgreSQL server¶

[server]
upload_folder = /var/lib/simdb/simulations
ssl_enabled = False
admin_password = CHANGE_ME

[flask]
secret_key = CHANGE_ME_TO_A_LONG_RANDOM_STRING

[database]
type = postgres
host = localhost
port = 5432
name = simdb

[authentication]
type = None

Validation schema¶

Servers can require specific metadata through a validation-schema.yaml file in the same configuration directory as app.cfg. It uses Cerberus rules:

description:
  required: true
  type: string

Clients can inspect the active schema with simdb remote SERVER schema. See Validation.

Server configuration¶

[database]¶

[server]¶

[flask]¶

[validation]¶

[file_validation]¶

[email]¶

[authentication]¶

Active Directory (type = ActiveDirectory)¶

LDAP (type = LDAP)¶

[cache]¶

[development]¶

[celery]¶

[partition]¶

[role "NAME"]¶