Server Configuration#

This page documents the QCFractal server configuration file format and all available options. Configuration is defined in YAML and mirrors the Pydantic settings in qcfractal/qcfractal/config.py. Options are grouped by sections according to the configuration hierarchy shown in that file.

Quick start#

Create a configuration file (for example server.yaml).
Run qcfractal-server init-config --config server.yaml to create an example config with secrets.
Start the server: qcfractal-server start --config server.yaml.

How configuration is loaded#

QCFractal merges configuration from multiple sources (later items have higher priority):

YAML files passed to --config in the order given (earlier files are lower priority).
extra_config from tooling (eg, CLI flags) if provided.
Environment variables. Environment variables override values provided by files.

Base folder detection#

Many options are paths that can be relative. Relative paths are resolved against a “base folder” using the following order:

QCF_BASE_FOLDER environment variable, if set.
base_folder key in the YAML.
The directory containing the last (highest-priority) config file passed to --config.

Durations and retention windows#

Options documented as “seconds” accept either integers (seconds) or duration strings like "1h", "30m", "2d 6h". They are converted internally.
Retention windows (eg, access_log_keep) accept days as integers or as duration strings (eg, 7 or "7d").

Environment variables#

You can set or override any option via environment variables. Every variable starts with the QCF_ prefix, followed by the name of the option in the YAML file (case does not matter).

For options at the root of the YAML document, that is all you need:

SHELL

export QCF_LOGLEVEL=DEBUG
export QCF_BASE_FOLDER=/srv/qcfractal
export QCF_MAX_ACTIVE_SERVICES=50

Options that live inside a nested section (database, api, api_limits, cors, auto_reset, s3) are reached by joining the section name and the option name with a double underscore. The section name is spelled exactly as it appears in the YAML - so api_limits becomes QCF_API_LIMITS__, not QCF_APILIMIT_.

SHELL

export QCF_DATABASE__HOST=db.example.org
export QCF_DATABASE__PORT=5432
export QCF_API__PORT=7777
export QCF_API_LIMITS__GET_RECORDS=2000
export QCF_AUTO_RESET__ENABLED=true
export QCF_S3__ENABLED=true
export QCF_CORS__ENABLED=true

Warning

Earlier versions of QCFractal used a separate flat prefix for each section (QCF_DB_, QCF_API_, QCF_APILIMIT_, QCF_AUTORESET_, QCF_S3_). None of these work any more, and rather than being ignored they are rejected - the server refuses to start and names the replacement:

SHELL

$ export QCF_DB_HOST=db.example.org
$ qcfractal-server start --config server.yaml
RuntimeError: Environment variable QCF_DB_HOST is deprecated. Use QCF_DATABASE__HOST instead.

The replacements are QCF_DB_ → QCF_DATABASE__, QCF_API_ → QCF_API__, QCF_APILIMIT_ → QCF_API_LIMITS__, QCF_AUTORESET_ → QCF_AUTO_RESET__, and QCF_S3_ → QCF_S3__. The check is case-insensitive, so a lowercase qcf_db_host is caught too.

Top-level settings (FractalConfig)#

These settings live at the root of the YAML document.

Required#

Option	Default	Description
`base_folder` (string)	required	The base directory to use as the default for some options (logs, etc). Default is the location of the config file.

If omitted from the file it is inferred, as described under base folder detection above.

General#

Option	Default	Description
`name` (string)	`"QCFractal Server"`	The QCFractal server name
`enable_security` (bool)	`true`	Enable user authentication and authorization
`allow_unauthenticated_read` (bool)	`true`	Allows unauthenticated read access to this instance. This does not extend to sensitive tables (such as user information)
`strict_compute_tags` (bool)	`false`	If True, disables wildcard behavior for compute tags. This disables managers from claiming all tags if they specify a wildcard (‘’) tag. Managers will still be able to claim tasks with an explicit ‘’ tag if they specify the ‘*’ queue tag in their config

The old name strict_queue_tags is still accepted for strict_compute_tags, but logs a deprecation warning.

Logging#

Option	Default	Description
`logfile` (string \| None)	`null`	Path to a file to use for server logging. If not specified, logs will be printed to standard output
`loglevel` (string)	`"INFO"`	Level of logging to enable (debug, info, warning, error, critical). Case insensitive
`hide_internal_errors` (bool)	`true`	If True, internal errors will only be reported as an error number to the user. If False, the entire error/backtrace will be sent (which could rarely contain sensitive info). In either case, errors will be stored in the database

loglevel is one of DEBUG, INFO, WARNING, ERROR, CRITICAL, case-insensitive. A relative logfile is resolved against base_folder; leaving it unset logs to standard output.

Background operations and heartbeats#

Option	Default	Description
`service_frequency` (int)	`60`	The frequency at which to update services (in seconds)
`max_active_services` (int)	`20`	The maximum number of concurrent active services
`heartbeat_frequency` (int)	`1800`	The frequency (in seconds) to check the heartbeat of compute managers
`heartbeat_frequency_jitter` (float)	`0.1`	Jitter fraction to be applied to the heartbeat frequency
`heartbeat_max_missed` (int)	`5`	The maximum number of heartbeats that a compute manager can miss. If more are missed, the worker is considered dead

A manager is considered dead after heartbeat_max_missed consecutive missed heartbeats - by default five checks at 1800 seconds, so about 2.5 hours. Its running tasks are returned to waiting to be claimed by another manager.

Access logging and internal jobs#

Option	Default	Description
`log_access` (bool)	`false`	Store API access in the database
`access_log_keep` (int)	`0`	How far back to keep access logs (in days or as a duration string). 0 means keep all
`internal_job_processes` (int)	`1`	Number of processes for processing internal jobs and async requests
`internal_job_keep` (int)	`0`	How far back to keep finished internal jobs (in days or as a duration string). 0 means keep all

Both retention windows are in days, or a duration string, and 0 means keep indefinitely.

GeoIP2 (optional)#

Option	Default	Description
`maxmind_license_key` (string \| None)	`null`	License key for MaxMind GeoIP2 service. If provided, the GeoIP2 database will be downloaded and updated automatically
`geoip2_dir` (string \| None)	`[base_folder]/geoip2`	Directory containing the Maxmind GeoIP2 Cities file (GeoLite2-City.mmdb) Defaults to [base_folder]/geoip2. This directory will be created if needed.
`geoip2_filename` (string)	`"GeoLite2-City.mmdb"`	Filename of the Maxmind GeoIP2 Cities file (GeoLite2-City.mmdb)

Static homepage and uploads (optional)#

Option	Default	Description
`homepage_redirect_url` (string \| None)	`null`	Redirect to this URL when going to the root path
`homepage_directory` (string \| None)	`null`	Use this directory to serve the homepage
`upload_directory` (string \| None)	`null`	Directory to store user-uploaded files for processing
`temporary_dir` (string \| None)	`[base_folder]/qcf_tmp`	Temporary directory to use for things such as view creation. If None, uses system default. This may require a lot of space!

If base_folder cannot be used, temporary_dir falls back to a qcf_tmp directory under the system temporary directory. It is created if it does not exist.

Nested sections#

The remaining top-level keys are the nested sections documented below.

Option	Default	Description
`database` (DatabaseConfig)	required	Configuration of the settings for the database
`api` (WebAPIConfig)	required	Configuration of the REST interface
`api_limits` (APILimitConfig)	see below	Configuration of the limits to the api
`cors` (CORSconfig)	see below	Configuration Cross Origin Resource sharing (advanced)
`auto_reset` (AutoResetConfig)	see below	Configuration for automatic resetting of tasks
`s3` (S3Config)	see below	Configuration of the S3 file storage (optional)

Database (database)#

Settings for the Postgres database connection and, optionally, managing the server’s own DB. Environment variable prefix: QCF_DATABASE__.

Connection#

Option	Default	Description
`full_uri` (string \| None)	`null`	Full connection URI. This overrides host,username,password,port, etc
`host` (string)	`"localhost"`	The hostname or ip address the database is running on. If own = True, this must be localhost. May also be a path to a directory containing the database socket file
`port` (int)	`5432`	The port the database is running on. If own = True, a database will be started, binding to this port
`database_name` (string)	`"qcfractal_default"`	The database name to connect to
`username` (string)	required	The database username to connect with
`password` (string)	required	The database password to connect with
`query` (dict[string, string \| int])	`{}`	Extra connection query parameters at the end of the URL string

query holds extra connection parameters appended to the URI, such as sslmode: require. Note that port is ignored when host is a Unix socket directory, though it is still used when rendering the URI.

Server-managed database#

Option	Default	Description
`own` (bool)	`true`	If True, QCFractal will control the database instance. If False, you must start and manage the database yourself
`data_directory` (string \| None)	`[base_folder]/postgres`	Location to place the database if own == True. Default is [base_folder]/database if we own the database
`logfile` (string \| None)	`[base_folder]/qcfractal_database.log`	Path to a file to use as the database logfile (if own == True). Default is [base_folder]/qcfractal_database.log
`pg_tool_dir` (string \| None)	`null`	Directory containing Postgres tools such as psql and pg_ctl (ie, /usr/bin, or /usr/lib/postgresql/13/bin). If not specified, an attempt to find them will be made. This field is only required if autodetection fails and own == True
`pool_size` (int)	`5`	[ADVANCED] set the size of the connection pool to use in SQLAlchemy. Set to zero to disable pooling
`maintenance_db` (string)	`"postgres"`	[ADVANCED] An existing database (not the one you want to use/create). This is used for database management
`echo_sql` (bool)	`false`	[ADVANCED] output raw SQL queries being run

The two path defaults apply when own is true. base_folder is inherited from the top level and is not set in this section.

Examples#

Minimal, managed Postgres (auto-start):

base_folder: /srv/qcfractal
database:
  own: true
  username: qcfractal
  password: "<generated>"

External Postgres:

database:
  own: false
  host: db.example.org
  port: 5432
  database_name: qcarchive
  username: qcfractal
  password: "<secret>"

Using a Unix domain socket directory:

database:
  host: /var/run/postgresql
  port: 5432
  database_name: qcarchive
  username: qcfractal
  password: "<secret>"

Web API (api)#

Settings for the HTTP API server. Environment variable prefix: QCF_API__.

Runtime#

Option	Default	Description
`host` (string)	`"localhost"`	The IP address or hostname to bind to
`port` (int)	`7777`	The port on which to run the REST interface
`num_threads_per_worker` (int)	`4`	Number of threads per worker
`worker_timeout` (int)	`120`	If the master process does not hear from a worker for the given amount of time (in seconds),kill it. This effectively limits the time a worker has to respond to a request

Security and sessions#

Both secret keys are required, and qcfractal-server init-config generates them for you.

Option	Default	Description
`secret_key` (string)	required	Secret key for flask api. See documentation
`jwt_secret_key` (string)	required	Secret key for web tokens. See documentation
`jwt_access_token_expires` (int)	`900`	The time (in seconds) an access token is valid for. Default is 15 minutes
`jwt_refresh_token_expires` (int)	`86400`	The time (in seconds) a refresh token is valid for. Default is 1 day
`user_session_max_age` (int)	`86400`	The time (in seconds) that a user session can be idle (for browser-based sessions)
`user_session_cookie_name` (string)	`"qcf_session"`	Name to use for a session cookie (for browser-based sessions)
`user_session_cookie_domain` (string \| None)	`null`	Domain to use for the user-session cookie (for browser-based sessions)
`user_session_cookie_samesite` (string \| None)	`null`	Set the SameSite flag for the user-session cookie (for browser-based sessions)
`user_session_cookie_partitioned` (bool)	`false`	Use the Partitioned flag for the user-session cookie (for browser-based sessions)
`user_session_cookie_secure` (bool)	`false`	Use Secure flag for the user-session cookie (for browser-based sessions)
`user_session_cookie_httponly` (bool)	`false`	Use Secure flag for the user-session cookie (for browser-based sessions)

For cross-site cookie behaviour set user_session_cookie_samesite to Lax or None as needed. user_session_cookie_partitioned sets the Partitioned flag, for CHIPS-style storage partitioning in modern browsers.

Advanced#

Option	Default	Description
`extra_flask_options` (dict[string, Any] \| None)	`null`	Any additional options to pass directly to flask
`extra_waitress_options` (dict[string, Any] \| None)	`null`	Any additional options to pass directly to the waitress serve function

These are passed straight through to Flask and to the waitress serve function respectively, so anything those accept is valid here and nothing is validated by QCFractal.

API limits (api_limits)#

Limits on sizes and pagination for common API calls. Environment variable prefix: QCF_API_LIMITS__.

Every option here is an integer, and every one is a hard ceiling: a request asking for more than the limit is not an error, it is silently truncated to the limit. Clients page through the results, so raising these mainly trades server memory for fewer round trips.

Option	Default	Description
`get_records` (int)	`1000`	Number of calculation records that can be retrieve in a single request
`add_records` (int)	`500`	Number of calculation records that can be added in a single request
`get_dataset_entries` (int)	`2000`	Number of dataset entries that can be retrieved in a single request
`get_molecules` (int)	`1000`	Number of molecules that can be retrieved in a single request
`add_molecules` (int)	`1000`	Number of molecules that can be added in a single request
`get_managers` (int)	`1000`	Number of manager records to return
`manager_tasks_claim` (int)	`200`	Number of tasks a single manager can pull down
`manager_tasks_return` (int)	`10`	Number of tasks a single manager can return at once
`get_access_logs` (int)	`1000`	Number of access log records to return
`get_error_logs` (int)	`100`	Number of error log records to return
`get_internal_jobs` (int)	`1000`	Number of internal jobs to return

Automatic resets (auto_reset)#

Limits on how often tasks may be automatically retried based on error type. Environment variable prefix: QCF_AUTO_RESET__.

Option	Default	Description
`enabled` (bool)	`false`	Whether to automatically reset errored records at all.
`unknown_error` (int)	`2`	Maximum automatic restarts for errors that could not be classified
`compute_lost` (int)	`5`	Maximum automatic restarts for computations whose compute resource disappeared.
`random_error` (int)	`5`	Maximum automatic restarts for errors the server recognises as intermittent

The counts are per record: once a record has been auto-reset that many times for that category of error, it is left in error for a human to look at. See A record has an error.

CORS (cors)#

Cross-Origin Resource Sharing settings for the API. Configure in YAML.

Option	Default	Description
`enabled` (bool)	`false`	Whether to send CORS headers at all. With this off the other options here do nothing.
`origins` (list[string])	`[]`	Origins permitted to make cross-origin requests. Use `["*"]` to allow any origin.
`supports_credentials` (bool)	`false`	Whether cross-origin requests may carry credentials (cookies, authorization headers)
`headers` (list[string])	`[]`	Request headers a cross-origin request is allowed to set, such as `Authorization`
`methods` (list[string])	`[]`	HTTP methods permitted for cross-origin requests. Empty means the CORS default.

Example:

cors:
  enabled: true
  origins: ["https://example.org", "http://localhost:3000"]
  supports_credentials: true
  headers: ["Content-Type", "Authorization"]
  methods: ["GET", "POST", "OPTIONS"]

S3 external files (s3)#

Settings for storing large external files in S3-compatible storage. Environment variable prefix: QCF_S3__.

Option	Default	Description
`enabled` (bool)	`false`	Whether to store large external files (dataset views, attachments) in S3.
`verify` (bool)	`true`	Verify TLS certificates when connecting to S3
`passthrough` (bool)	`false`	Whether clients may download directly from the S3 endpoint.
`endpoint_url` (string \| None)	`null`	S3 endpoint URL
`access_key_id` (string \| None)	`null`	AWS/S3 access key
`secret_access_key` (string \| None)	`null`	AWS/S3 secret key
`auto_create_buckets` (bool)	`false`	Create the buckets named in `bucket_map` at startup if they do not already exist
`bucket_map` (S3BucketMap)	see below	Configuration for where to store various files

bucket_map maps each logical file type to a bucket name:

Option	Default	Description
`dataset_attachment` (string)	`"dataset-attachments"`	Bucket to hold dataset views
`project_attachment` (string)	`"project-attachments"`	Bucket to hold project attachments

Note

Bucket names must be valid S3 bucket names: 3-63 characters, lowercase letters, digits and hyphens only, ending in a letter or digit. Underscores are not allowed, so a value like dataset_attachment will be rejected at startup.

If enabled: true you must specify endpoint_url, access_key_id, and secret_access_key.

Example:

s3:
  enabled: true
  endpoint_url: https://s3.us-west-2.amazonaws.com
  access_key_id: ${AWS_ACCESS_KEY_ID}
  secret_access_key: ${AWS_SECRET_ACCESS_KEY}
  verify: true
  bucket_map:
    dataset_attachment: qcarchive-attachments
    project_attachment: qcarchive-projects

Minimal and full configuration examples#

Minimal (sensible defaults; secrets generated by qcfractal-server init-config):

base_folder: /srv/qcfractal
name: QCFractal Server
enable_security: true
allow_unauthenticated_read: true

database:
  own: true
  username: qcfractal
  password: "<generated>"

api:
  host: 0.0.0.0
  port: 7777
  secret_key: "<generated>"
  jwt_secret_key: "<generated>"

api_limits: {}
cors: {}
auto_reset: {}

Full skeleton (all options with defaults; adjust as needed):

base_folder: /srv/qcfractal
name: QCFractal Server
enable_security: true
allow_unauthenticated_read: true
strict_compute_tags: false
logfile: null
loglevel: INFO
hide_internal_errors: true
service_frequency: 60
max_active_services: 20
heartbeat_frequency: 1800
heartbeat_frequency_jitter: 0.1
heartbeat_max_missed: 5
log_access: false
access_log_keep: 0
internal_job_processes: 1
internal_job_keep: 0
maxmind_license_key: null
geoip2_dir: geoip2
geoip2_filename: GeoLite2-City.mmdb
homepage_redirect_url: null
homepage_directory: null
upload_directory: null
temporary_dir: null

database:
  full_uri: null
  host: localhost
  port: 5432
  database_name: qcfractal_default
  username: qcfractal
  password: "<secret>"
  query: {}
  own: true
  data_directory: postgres
  logfile: qcfractal_database.log
  echo_sql: false
  pg_tool_dir: null
  pool_size: 5
  maintenance_db: postgres

api:
  num_threads_per_worker: 4
  worker_timeout: 120
  host: localhost
  port: 7777
  secret_key: "<secret>"
  jwt_secret_key: "<secret>"
  jwt_access_token_expires: 3600
  jwt_refresh_token_expires: 86400
  user_session_max_age: 86400
  user_session_cookie_name: qcf_session
  user_session_cookie_domain: null
  user_session_cookie_samesite: null
  user_session_cookie_partitioned: false
  user_session_cookie_secure: false
  user_session_cookie_httponly: false
  extra_flask_options: null
  extra_waitress_options: null

api_limits:
  get_records: 1000
  add_records: 500
  get_dataset_entries: 2000
  get_molecules: 1000
  add_molecules: 1000
  get_managers: 1000
  manager_tasks_claim: 200
  manager_tasks_return: 10
  get_access_logs: 1000
  get_error_logs: 100
  get_internal_jobs: 1000

cors:
  enabled: false
  origins: []
  supports_credentials: false
  headers: []
  methods: []

auto_reset:
  enabled: false
  unknown_error: 2
  compute_lost: 5
  random_error: 5

s3:
  enabled: false
  verify: true
  passthrough: false
  endpoint_url: null
  access_key_id: null
  secret_access_key: null
  auto_create_buckets: false
  bucket_map:
    dataset_attachment: dataset-attachments
    project_attachment: project-attachments

Environment variable examples#

Override the base folder and database host on the fly:

export QCF_BASE_FOLDER=/srv/qcfractal
export QCF_DATABASE__HOST=db.internal
qcfractal-server start --config server.yaml

Bind the API to a different port and enable verbose logging:

export QCF_API__PORT=8888
export QCF_LOGLEVEL=DEBUG
qcfractal-server start --config server.yaml

Notes on path handling#

Paths that are not absolute are resolved relative to base_folder.
If a path option is null and a default is described as [base_folder]/..., QCFractal will apply that default at runtime.
temporary_dir is created automatically if it does not exist.

Generated reference#

The sections above are the documentation for these options - they explain what the options are for, how they interact, and what sensible values look like. What follows is generated directly from the pydantic models in qcfractal/qcfractal/config.py, and is here as a cross-check: it is guaranteed to list every option that actually exists, with its real type and default.

Where the two disagree, this section is right about what the code accepts and the prose above is right about why.

Note

A few defaults are shown here as None but are filled in at runtime - geoip2_dir, temporary_dir, the database data_directory and logfile. The prose above gives the effective values ([base_folder]/...). Likewise, options described above as accepting duration strings appear here as int, since that is the type they are converted to.

class FractalConfig[source]#

Bases: BaseSettings

Fractal Server settings

Fields#
Field	Type	Required	Default	Constraints
`access_log_keep`	`int`	No	`0`
`allow_unauthenticated_read`	`bool`	No	`True`
`api`	`WebAPIConfig`	Yes
`api_limits`	`APILimitConfig`	No	factory
`auto_reset`	`AutoResetConfig`	No	factory
`base_folder`	`str`	Yes
`cors`	`CORSconfig`	No	factory
`database`	`DatabaseConfig`	Yes
`enable_security`	`bool`	No	`True`
`geoip2_dir`	`str` \| `None`	No	`None`
`geoip2_filename`	`str`	No	`'GeoLite2-City.mmdb'`
`heartbeat_frequency`	`int`	No	`1800`	gt=0
`heartbeat_frequency_jitter`	`float`	No	`0.1`	ge=0
`heartbeat_max_missed`	`int`	No	`5`	ge=0
`hide_internal_errors`	`bool`	No	`True`
`homepage_directory`	`str` \| `None`	No	`None`
`homepage_redirect_url`	`str` \| `None`	No	`None`
`internal_job_keep`	`int`	No	`0`
`internal_job_processes`	`int`	No	`1`
`log_access`	`bool`	No	`False`
`logfile`	`str` \| `None`	No	`None`
`loglevel`	`str`	No	`'INFO'`
`max_active_services`	`int`	No	`20`
`maxmind_license_key`	`str` \| `None`	No	`None`
`name`	`str`	No	`'QCFractal Server'`
`s3`	`S3Config`	No	factory
`service_frequency`	`int`	No	`60`
`strict_compute_tags`	`bool`	No	`False`
`temporary_dir`	`str` \| `None`	No	`None`
`upload_directory`	`str` \| `None`	No	`None`

classmethod __new__(*args, **kwargs)#

base_folder: str#: The base directory to use as the default for some options (logs, etc). Default is the location of the config file.

temporary_dir: str | None#: Temporary directory to use for things such as view creation. If None, uses system default. This may require a lot of space!

name: str#: The QCFractal server name

enable_security: bool#: Enable user authentication and authorization

allow_unauthenticated_read: bool#: Allows unauthenticated read access to this instance. This does not extend to sensitive tables (such as user information)

strict_compute_tags: bool#: If True, disables wildcard behavior for compute tags. This disables managers from claiming all tags if they specify a wildcard (‘*’) tag. Managers will still be able to claim tasks with an explicit ‘*’ tag if they specify the ‘*’ queue tag in their config

logfile: str | None#: Path to a file to use for server logging. If not specified, logs will be printed to standard output

loglevel: str#: Level of logging to enable (debug, info, warning, error, critical). Case insensitive

hide_internal_errors: bool#: If True, internal errors will only be reported as an error number to the user. If False, the entire error/backtrace will be sent (which could rarely contain sensitive info). In either case, errors will be stored in the database

service_frequency: int#: The frequency at which to update services (in seconds)

max_active_services: int#: The maximum number of concurrent active services

heartbeat_frequency: int#

The frequency (in seconds) to check the heartbeat of compute managers

Constraints:

gt = 0

heartbeat_frequency_jitter: float#

Jitter fraction to be applied to the heartbeat frequency

Constraints:

ge = 0

heartbeat_max_missed: int#

The maximum number of heartbeats that a compute manager can miss. If more are missed, the worker is considered dead

Constraints:

ge = 0

log_access: bool#: Store API access in the database

access_log_keep: int#: How far back to keep access logs (in days or as a duration string). 0 means keep all

maxmind_license_key: str | None#: License key for MaxMind GeoIP2 service. If provided, the GeoIP2 database will be downloaded and updated automatically

geoip2_dir: str | None#: Directory containing the Maxmind GeoIP2 Cities file (GeoLite2-City.mmdb) Defaults to [base_folder]/geoip2. This directory will be created if needed.

geoip2_filename: str#: Filename of the Maxmind GeoIP2 Cities file (GeoLite2-City.mmdb)

internal_job_processes: int#: Number of processes for processing internal jobs and async requests

internal_job_keep: int#: How far back to keep finished internal jobs (in days or as a duration string). 0 means keep all

homepage_redirect_url: str | None#: Redirect to this URL when going to the root path

homepage_directory: str | None#: Use this directory to serve the homepage

upload_directory: str | None#: Directory to store user-uploaded files for processing

database: DatabaseConfig#: Configuration of the settings for the database

api: WebAPIConfig#: Configuration of the REST interface

s3: S3Config#: Configuration of the S3 file storage (optional)

api_limits: APILimitConfig#: Configuration of the limits to the api

cors: CORSconfig#: Configuration Cross Origin Resource sharing (advanced)

auto_reset: AutoResetConfig#: Configuration for automatic resetting of tasks

class DatabaseConfig[source]#

Bases: QCFConfigBase

Settings for the database used by QCFractal

Fields#
Field	Type	Required	Default
`base_folder`	`str`	Yes
`data_directory`	`str` \| `None`	No	`None`
`database_name`	`str`	No	`'qcfractal_default'`
`echo_sql`	`bool`	No	`False`
`full_uri`	`str` \| `None`	No	`None`
`host`	`str`	No	`'localhost'`
`logfile`	`str` \| `None`	No	`None`
`maintenance_db`	`str`	No	`'postgres'`
`own`	`bool`	No	`True`
`password`	`str`	Yes
`pg_tool_dir`	`str` \| `None`	No	`None`
`pool_size`	`int`	No	`5`
`port`	`int`	No	`5432`
`query`	`dict`[`str`, `str` \| `int`]	No	`{}`
`username`	`str`	Yes

base_folder: str#: The base folder to use as the default for some options (logs, etc). Default is the location of the config file.

full_uri: str | None#: Full connection URI. This overrides host,username,password,port, etc

host: str#: The hostname or ip address the database is running on. If own = True, this must be localhost. May also be a path to a directory containing the database socket file

port: int#: The port the database is running on. If own = True, a database will be started, binding to this port

database_name: str#: The database name to connect to

username: str#: The database username to connect with

password: str#: The database password to connect with

query: dict[str, str | int]#: Extra connection query parameters at the end of the URL string

own: bool#: If True, QCFractal will control the database instance. If False, you must start and manage the database yourself

data_directory: str | None#: Location to place the database if own == True. Default is [base_folder]/database if we own the database

logfile: str | None#: Path to a file to use as the database logfile (if own == True). Default is [base_folder]/qcfractal_database.log

echo_sql: bool#: [ADVANCED] output raw SQL queries being run

pg_tool_dir: str | None#: Directory containing Postgres tools such as psql and pg_ctl (ie, /usr/bin, or /usr/lib/postgresql/13/bin). If not specified, an attempt to find them will be made. This field is only required if autodetection fails and own == True

pool_size: int#: [ADVANCED] set the size of the connection pool to use in SQLAlchemy. Set to zero to disable pooling

maintenance_db: str#: [ADVANCED] An existing database (not the one you want to use/create). This is used for database management

property database_uri: str#

Returns the real database URI as a string

It does not hide the password, so is not suitable for logging

property sqlalchemy_url: URL#: Returns the SQLAlchemy URL for this database

property psycopg2_dsn: str#: Returns a string suitable for use as a psycopg2 connection string

property psycopg2_maintenance_dsn: str#

property safe_uri: str#: Returns a user-readable version of the URI for logging, etc.

class WebAPIConfig[source]#

Bases: QCFConfigBase

Settings for the Web API (api) interface

Fields#
Field	Type	Required	Default
`extra_flask_options`	`dict`[`str`, `Any`] \| `None`	No	`None`
`extra_waitress_options`	`dict`[`str`, `Any`] \| `None`	No	`None`
`host`	`str`	No	`'localhost'`
`jwt_access_token_expires`	`int`	No	`900`
`jwt_refresh_token_expires`	`int`	No	`86400`
`jwt_secret_key`	`str`	Yes
`num_threads_per_worker`	`int`	No	`4`
`port`	`int`	No	`7777`
`secret_key`	`str`	Yes
`user_session_cookie_domain`	`str` \| `None`	No	`None`
`user_session_cookie_httponly`	`bool`	No	`False`
`user_session_cookie_name`	`str`	No	`'qcf_session'`
`user_session_cookie_partitioned`	`bool`	No	`False`
`user_session_cookie_samesite`	`str` \| `None`	No	`None`
`user_session_cookie_secure`	`bool`	No	`False`
`user_session_max_age`	`int`	No	`86400`
`worker_timeout`	`int`	No	`120`

num_threads_per_worker: int#: Number of threads per worker

worker_timeout: int#: If the master process does not hear from a worker for the given amount of time (in seconds),kill it. This effectively limits the time a worker has to respond to a request

host: str#: The IP address or hostname to bind to

port: int#: The port on which to run the REST interface

secret_key: str#: Secret key for flask api. See documentation

jwt_secret_key: str#: Secret key for web tokens. See documentation

jwt_access_token_expires: int#: The time (in seconds) an access token is valid for. Default is 15 minutes

jwt_refresh_token_expires: int#: The time (in seconds) a refresh token is valid for. Default is 1 day

user_session_max_age: int#: The time (in seconds) that a user session can be idle (for browser-based sessions)

user_session_cookie_name: str#: Name to use for a session cookie (for browser-based sessions)

user_session_cookie_domain: str | None#: Domain to use for the user-session cookie (for browser-based sessions)

user_session_cookie_samesite: str | None#: Set the SameSite flag for the user-session cookie (for browser-based sessions)

user_session_cookie_partitioned: bool#: Use the Partitioned flag for the user-session cookie (for browser-based sessions)

user_session_cookie_secure: bool#: Use Secure flag for the user-session cookie (for browser-based sessions)

user_session_cookie_httponly: bool#: Use Secure flag for the user-session cookie (for browser-based sessions)

extra_flask_options: dict[str, Any] | None#: Any additional options to pass directly to flask

extra_waitress_options: dict[str, Any] | None#: Any additional options to pass directly to the waitress serve function

class APILimitConfig[source]#

Bases: QCFConfigBase

Limits on the number of records returned per query. This can be specified per object (molecule, etc)

Fields#
Field	Type	Required	Default
`add_molecules`	`int`	No	`1000`
`add_records`	`int`	No	`500`
`get_access_logs`	`int`	No	`1000`
`get_dataset_entries`	`int`	No	`2000`
`get_error_logs`	`int`	No	`100`
`get_internal_jobs`	`int`	No	`1000`
`get_managers`	`int`	No	`1000`
`get_molecules`	`int`	No	`1000`
`get_records`	`int`	No	`1000`
`manager_tasks_claim`	`int`	No	`200`
`manager_tasks_return`	`int`	No	`10`

get_records: int#: Number of calculation records that can be retrieve in a single request

add_records: int#: Number of calculation records that can be added in a single request

get_dataset_entries: int#: Number of dataset entries that can be retrieved in a single request

get_molecules: int#: Number of molecules that can be retrieved in a single request

add_molecules: int#: Number of molecules that can be added in a single request

get_managers: int#: Number of manager records to return

manager_tasks_claim: int#: Number of tasks a single manager can pull down

manager_tasks_return: int#: Number of tasks a single manager can return at once

get_access_logs: int#: Number of access log records to return

get_error_logs: int#: Number of error log records to return

get_internal_jobs: int#: Number of internal jobs to return

class AutoResetConfig[source]#

Bases: QCFConfigBase

How many times the server will automatically retry a failed computation

Fields#
Field	Type	Required	Default
`compute_lost`	`int`	No	`5`
`enabled`	`bool`	No	`False`
`random_error`	`int`	No	`5`
`unknown_error`	`int`	No	`2`

enabled: bool#

Whether to automatically reset errored records at all.

With this disabled, every errored record waits for someone to reset it by hand.

unknown_error: int#: Maximum automatic restarts for errors that could not be classified

compute_lost: int#

Maximum automatic restarts for computations whose compute resource disappeared.

This covers the ordinary ways a batch job ends without reporting back - a walltime kill, a preempted node, a manager killed mid-task. These failures say nothing about whether the computation itself is sound, which is why the default is more generous than for unknown_error.

random_error: int#: Maximum automatic restarts for errors the server recognises as intermittent

class CORSconfig[source]#

Bases: QCFConfigBase

Settings for using CORS

Fields#
Field	Type	Required	Default
`enabled`	`bool`	No	`False`
`headers`	`list`[`str`]	No	`[]`
`methods`	`list`[`str`]	No	`[]`
`origins`	`list`[`str`]	No	`[]`
`supports_credentials`	`bool`	No	`False`

enabled: bool#: Whether to send CORS headers at all. With this off the other options here do nothing.

origins: list[str]#: Origins permitted to make cross-origin requests. Use ["*"] to allow any origin.

supports_credentials: bool#: Whether cross-origin requests may carry credentials (cookies, authorization headers)

headers: list[str]#: Request headers a cross-origin request is allowed to set, such as Authorization

methods: list[str]#: HTTP methods permitted for cross-origin requests. Empty means the CORS default.

class S3Config[source]#

Bases: QCFConfigBase

Settings for using external files with S3

Fields#
Field	Type	Required	Default
`access_key_id`	`str` \| `None`	No	`None`
`auto_create_buckets`	`bool`	No	`False`
`bucket_map`	`S3BucketMap`	No	factory
`enabled`	`bool`	No	`False`
`endpoint_url`	`str` \| `None`	No	`None`
`passthrough`	`bool`	No	`False`
`secret_access_key`	`str` \| `None`	No	`None`
`verify`	`bool`	No	`True`

enabled: bool#

Whether to store large external files (dataset views, attachments) in S3.

When enabled, endpoint_url, access_key_id and secret_access_key are all required; the server refuses to start otherwise.

verify: bool#: Verify TLS certificates when connecting to S3

passthrough: bool#

Whether clients may download directly from the S3 endpoint.

With this off, file contents are proxied through the server, so clients never need to reach S3 themselves.

endpoint_url: str | None#: S3 endpoint URL

access_key_id: str | None#: AWS/S3 access key

secret_access_key: str | None#: AWS/S3 secret key

auto_create_buckets: bool#: Create the buckets named in bucket_map at startup if they do not already exist

bucket_map: S3BucketMap#: Configuration for where to store various files

class S3BucketMap[source]#

Bases: QCFConfigBase

Fields#
Field	Type	Required	Default	Constraints
`dataset_attachment`	`str`	No	`'dataset-attachments'`	min_length=3, max_length=63, pattern=``^[a-z0-9-]+[a-z0-9]$``
`project_attachment`	`str`	No	`'project-attachments'`	min_length=3, max_length=63, pattern=``^[a-z0-9-]+[a-z0-9]$``

dataset_attachment: StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=63, pattern=^[a-z0-9\-]+[a-z0-9]$, ascii_only=None)]#

Bucket to hold dataset views

Constraints:

min_length = 3
max_length = 63
pattern = ^[a-z0-9\-]+[a-z0-9]$

project_attachment: StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=63, pattern=^[a-z0-9\-]+[a-z0-9]$, ascii_only=None)]#

Bucket to hold project attachments

Constraints:

min_length = 3
max_length = 63
pattern = ^[a-z0-9\-]+[a-z0-9]$