Configuration

Set configuration variables¶

There are two possibilities for setting the configuration variables that determine the settings for fractal-server:

Define them as environment variables, in the same environment where the fractal-server process will runs:
```
export VARIABLE1=value1
export VARIABLE2=value2
```
Write them inside a file named .fractal_server.env, in your current working directory, with contents like
```
VARIABLE1=value1
VARIABLE2=value2
```

Once the variables have been defined in one of these ways, they will be read automatically by the Fractal Server during the start-up phase.

If the same variable is defined twice, both as an environment variable and inside the .fractal_server.env file, the value defined in the environment takes priority.

Get current configuration¶

Admins can retrieve the current settings through the appropriate endpoints GET /api/settings/.

Configuration variables¶

Here are all the configuration variables with their description (note: expand the "Source code" blocks to see the default values).

`Settings` ¶

Bases: BaseSettings

Contains the general configuration variables for Fractal Server.

ATTRIBUTE	DESCRIPTION
`JWT_EXPIRE_SECONDS`	JWT token lifetime, in seconds. TYPE: `int`
`JWT_SECRET_KEY`	JWT secret. ⚠️ Set this variable to a secure string, and do not disclose it. TYPE: `SecretStr`
`COOKIE_EXPIRE_SECONDS`	Cookie token lifetime, in seconds. TYPE: `int`
`FRACTAL_RUNNER_BACKEND`	Select which runner backend to use. TYPE: `Literal['local', 'slurm_ssh', 'slurm_sudo']`
`FRACTAL_LOGGING_LEVEL`	Logging-level threshold for logging Only logs of with this level (or higher) will appear in the console logs. TYPE: `int`
`FRACTAL_API_MAX_JOB_LIST_LENGTH`	Number of ids that can be stored in the `jobs` attribute of `app.state`. TYPE: `int`
`FRACTAL_GRACEFUL_SHUTDOWN_TIME`	Waiting time for the shutdown phase of executors, in seconds. TYPE: `float`
`FRACTAL_HELP_URL`	The URL of an instance-specific Fractal help page. TYPE: `HttpUrl \| None`
`FRACTAL_DEFAULT_GROUP_NAME`	Name of the default user group. If set to `"All"`, then the user group with that name is a special user group (e.g. it cannot be deleted, and new users are automatically added to it). If set to `None` (the default value), then user groups are all equivalent, independently on their name. TYPE: `Literal['All'] \| None`
`FRACTAL_LONG_REQUEST_TIME`	Time limit beyond which the execution of an API request is considered slow and an appropriate warning is logged by the middleware. TYPE: `float`
`FRACTAL_DISABLE_BASIC_AUTH`	Remove endpoints starting with `/token/login`. TYPE: `Literal['true', 'false']`
`FRACTAL_ENABLE_TASK_GROUP_RESET`	Enable admin-only endpoint to reset task groups. TYPE: `Literal['true', 'false']`

Source code in fractal_server/config/_main.py

class Settings(BaseSettings):
    """
    Contains the general configuration variables for Fractal Server.

    Attributes:
        JWT_EXPIRE_SECONDS:
            JWT token lifetime, in seconds.
        JWT_SECRET_KEY:
            JWT secret.<br>
            ⚠️ Set this variable to a secure string, and do not disclose it.
        COOKIE_EXPIRE_SECONDS:
            Cookie token lifetime, in seconds.
        FRACTAL_RUNNER_BACKEND:
            Select which runner backend to use.
        FRACTAL_LOGGING_LEVEL:
            Logging-level threshold for logging
            Only logs of with this level (or higher) will appear in the console
            logs.
        FRACTAL_API_MAX_JOB_LIST_LENGTH:
            Number of ids that can be stored in the `jobs` attribute of
            `app.state`.
        FRACTAL_GRACEFUL_SHUTDOWN_TIME:
            Waiting time for the shutdown phase of executors, in seconds.
        FRACTAL_HELP_URL:
            The URL of an instance-specific Fractal help page.
        FRACTAL_DEFAULT_GROUP_NAME:
            Name of the default user group.

            If set to `"All"`, then the user group with that name is a special
            user group (e.g. it cannot be deleted, and new users are
            automatically added to it). If set to `None` (the default value),
            then user groups are all equivalent, independently on their name.
        FRACTAL_LONG_REQUEST_TIME:
            Time limit beyond which the execution of an API request is
            considered *slow* and an appropriate warning is logged by the
            middleware.
        FRACTAL_DISABLE_BASIC_AUTH:
            Remove endpoints starting with `/token/login`.
        FRACTAL_ENABLE_TASK_GROUP_RESET:
            Enable admin-only endpoint to reset task groups.
    """

    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)

    JWT_EXPIRE_SECONDS: int = 180
    JWT_SECRET_KEY: SecretStr
    COOKIE_EXPIRE_SECONDS: int = 86400
    # Note: we do not use ResourceType here to avoid circular imports
    FRACTAL_RUNNER_BACKEND: Literal["local", "slurm_ssh", "slurm_sudo"] = (
        "local"
    )
    FRACTAL_LOGGING_LEVEL: int = logging.INFO
    FRACTAL_API_MAX_JOB_LIST_LENGTH: int = 25
    FRACTAL_GRACEFUL_SHUTDOWN_TIME: float = 30.0
    FRACTAL_HELP_URL: HttpUrl | None = None
    FRACTAL_DEFAULT_GROUP_NAME: Literal["All"] | None = None
    FRACTAL_LONG_REQUEST_TIME: float = 30.0
    FRACTAL_DISABLE_BASIC_AUTH: Literal["true", "false"] = "false"
    FRACTAL_ENABLE_TASK_GROUP_RESET: Literal["true", "false"] = "false"

`DatabaseSettings` ¶

Bases: BaseSettings

Minimal set of configurations needed for operating on the database (e.g for schema migrations).

ATTRIBUTE	DESCRIPTION
`DB_ECHO`	If `"true"`, make database operations verbose. TYPE: `Literal['true', 'false']`
`POSTGRES_USER`	User to use when connecting to the PostgreSQL database. TYPE: `NonEmptyStr \| None`
`POSTGRES_PASSWORD`	Password to use when connecting to the PostgreSQL database. TYPE: `SecretStr \| None`
`POSTGRES_HOST`	URL to the PostgreSQL server or path to a UNIX domain socket. TYPE: `NonEmptyStr`
`POSTGRES_PORT`	Port number to use when connecting to the PostgreSQL server. TYPE: `NonNegativeInt`
`POSTGRES_DB`	Name of the PostgreSQL database to connect to. TYPE: `NonEmptyStr`

Source code in fractal_server/config/_database.py

class DatabaseSettings(BaseSettings):
    """
    Minimal set of configurations needed for operating on the database (e.g
    for schema migrations).

    Attributes:
        DB_ECHO:
            If `"true"`, make database operations verbose.
        POSTGRES_USER:
            User to use when connecting to the PostgreSQL database.
        POSTGRES_PASSWORD:
            Password to use when connecting to the PostgreSQL database.
        POSTGRES_HOST:
            URL to the PostgreSQL server or path to a UNIX domain socket.
        POSTGRES_PORT:
            Port number to use when connecting to the PostgreSQL server.
        POSTGRES_DB:
            Name of the PostgreSQL database to connect to.
    """

    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)

    DB_ECHO: Literal["true", "false"] = "false"
    POSTGRES_USER: NonEmptyStr | None = None
    POSTGRES_PASSWORD: SecretStr | None = None
    POSTGRES_HOST: NonEmptyStr = "localhost"
    POSTGRES_PORT: NonNegativeInt = 5432
    POSTGRES_DB: NonEmptyStr

    @property
    def DATABASE_URL(self) -> URL:
        if self.POSTGRES_PASSWORD is None:
            password = None
        else:
            password = self.POSTGRES_PASSWORD.get_secret_value()

        url = URL.create(
            drivername="postgresql+psycopg",
            username=self.POSTGRES_USER,
            password=password,
            host=self.POSTGRES_HOST,
            port=self.POSTGRES_PORT,
            database=self.POSTGRES_DB,
        )
        return url

`EmailSettings` ¶

Bases: BaseSettings

Class with settings for email-sending feature.

ATTRIBUTE	DESCRIPTION
`FRACTAL_EMAIL_SENDER`	Address of the OAuth-signup email sender. TYPE: `EmailStr \| None`
`FRACTAL_EMAIL_PASSWORD`	Password for the OAuth-signup email sender. TYPE: `SecretStr \| None`
`FRACTAL_EMAIL_SMTP_SERVER`	SMTP server for the OAuth-signup emails. TYPE: `str \| None`
`FRACTAL_EMAIL_SMTP_PORT`	SMTP server port for the OAuth-signup emails. TYPE: `int \| None`
`FRACTAL_EMAIL_INSTANCE_NAME`	Fractal instance name, to be included in the OAuth-signup emails. TYPE: `str \| None`
`FRACTAL_EMAIL_RECIPIENTS`	Comma-separated list of recipients of the OAuth-signup emails. TYPE: `str \| None`
`FRACTAL_EMAIL_USE_STARTTLS`	Whether to use StartTLS when using the SMTP server. TYPE: `Literal['true', 'false']`
`FRACTAL_EMAIL_USE_LOGIN`	Whether to use login when using the SMTP server. If 'true', FRACTAL_EMAIL_PASSWORD must be provided. TYPE: `Literal['true', 'false']`

Source code in fractal_server/config/_email.py

class EmailSettings(BaseSettings):
    """
    Class with settings for email-sending feature.

    Attributes:
        FRACTAL_EMAIL_SENDER:
            Address of the OAuth-signup email sender.
        FRACTAL_EMAIL_PASSWORD:
            Password for the OAuth-signup email sender.
        FRACTAL_EMAIL_SMTP_SERVER:
            SMTP server for the OAuth-signup emails.
        FRACTAL_EMAIL_SMTP_PORT:
            SMTP server port for the OAuth-signup emails.
        FRACTAL_EMAIL_INSTANCE_NAME:
            Fractal instance name, to be included in the OAuth-signup emails.
        FRACTAL_EMAIL_RECIPIENTS:
            Comma-separated list of recipients of the OAuth-signup emails.
        FRACTAL_EMAIL_USE_STARTTLS:
            Whether to use StartTLS when using the SMTP server.
        FRACTAL_EMAIL_USE_LOGIN:
            Whether to use login when using the SMTP server.
            If 'true', FRACTAL_EMAIL_PASSWORD  must be provided.
    """

    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)

    FRACTAL_EMAIL_SENDER: EmailStr | None = None
    FRACTAL_EMAIL_PASSWORD: SecretStr | None = None
    FRACTAL_EMAIL_SMTP_SERVER: str | None = None
    FRACTAL_EMAIL_SMTP_PORT: int | None = None
    FRACTAL_EMAIL_INSTANCE_NAME: str | None = None
    FRACTAL_EMAIL_RECIPIENTS: str | None = None
    FRACTAL_EMAIL_USE_STARTTLS: Literal["true", "false"] = "true"
    FRACTAL_EMAIL_USE_LOGIN: Literal["true", "false"] = "true"

    public: PublicEmailSettings | None = None
    """
    The validated field which is actually used in `fractal-server`,
    automatically populated upon creation.
    """

    @model_validator(mode="after")
    def validate_email_settings(self: Self) -> Self:
        """
        Set `self.public`.
        """

        email_values = [
            self.FRACTAL_EMAIL_SENDER,
            self.FRACTAL_EMAIL_SMTP_SERVER,
            self.FRACTAL_EMAIL_SMTP_PORT,
            self.FRACTAL_EMAIL_INSTANCE_NAME,
            self.FRACTAL_EMAIL_RECIPIENTS,
        ]
        if len(set(email_values)) == 1:
            # All required EMAIL attributes are None
            pass
        elif None in email_values:
            # Not all required EMAIL attributes are set
            error_msg = (
                "Invalid FRACTAL_EMAIL configuration. "
                f"Given values: {email_values}."
            )
            raise ValueError(error_msg)
        else:
            use_starttls = self.FRACTAL_EMAIL_USE_STARTTLS == "true"
            use_login = self.FRACTAL_EMAIL_USE_LOGIN == "true"

            if use_login and self.FRACTAL_EMAIL_PASSWORD is None:
                raise ValueError(
                    "'FRACTAL_EMAIL_USE_LOGIN' is 'true' but "
                    "'FRACTAL_EMAIL_PASSWORD' is not provided."
                )

            self.public = PublicEmailSettings(
                sender=self.FRACTAL_EMAIL_SENDER,
                recipients=self.FRACTAL_EMAIL_RECIPIENTS.split(","),
                smtp_server=self.FRACTAL_EMAIL_SMTP_SERVER,
                port=self.FRACTAL_EMAIL_SMTP_PORT,
                password=self.FRACTAL_EMAIL_PASSWORD,
                instance_name=self.FRACTAL_EMAIL_INSTANCE_NAME,
                use_starttls=use_starttls,
                use_login=use_login,
            )

        return self

`OAuthSettings` ¶

Bases: BaseSettings

Settings for integration with an OAuth identity provider.

ATTRIBUTE	DESCRIPTION
`OAUTH_CLIENT_NAME`	Name of the client. TYPE: `Annotated[NonEmptyStr, StringConstraints(to_lower=True)] \| None`
`OAUTH_CLIENT_ID`	ID of client. TYPE: `SecretStr \| None`
`OAUTH_CLIENT_SECRET`	Secret to authorise against the identity provider. TYPE: `SecretStr \| None`
`OAUTH_OIDC_CONFIG_ENDPOINT`	OpenID Connect configuration endpoint, for autodiscovery of relevant endpoints. TYPE: `SecretStr \| None`
`OAUTH_REDIRECT_URL`	String to be used as `redirect_url` argument in `fastapi_users.get_oauth_router`, and then in `httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback`. TYPE: `str \| None`
`OAUTH_EMAIL_CLAIM`	Name of the OIDC claim with the user's email address. This is `"email"` by default, but can be customized (e.g. to `"mail"`) to fit with the response from the userinfo endpoint - see https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse TYPE: `str`

Source code in fractal_server/config/_oauth.py

class OAuthSettings(BaseSettings):
    """
    Settings for integration with an OAuth identity provider.

    Attributes:
        OAUTH_CLIENT_NAME: Name of the client.
        OAUTH_CLIENT_ID: ID of client.
        OAUTH_CLIENT_SECRET:
            Secret to authorise against the identity provider.
        OAUTH_OIDC_CONFIG_ENDPOINT:
            OpenID Connect configuration endpoint, for autodiscovery of
            relevant endpoints.
        OAUTH_REDIRECT_URL:
            String to be used as `redirect_url` argument in
            `fastapi_users.get_oauth_router`, and then in
            `httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback`.
        OAUTH_EMAIL_CLAIM:
            Name of the OIDC claim with the user's email address. This is
            `"email"` by default, but can be customized (e.g. to `"mail"`) to
            fit with the response from the userinfo endpoint - see
            https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse
    """

    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)

    OAUTH_CLIENT_NAME: (
        Annotated[
            NonEmptyStr,
            StringConstraints(to_lower=True),
        ]
        | None
    ) = None
    OAUTH_CLIENT_ID: SecretStr | None = None
    OAUTH_CLIENT_SECRET: SecretStr | None = None
    OAUTH_OIDC_CONFIG_ENDPOINT: SecretStr | None = None
    OAUTH_REDIRECT_URL: str | None = None
    OAUTH_EMAIL_CLAIM: str = "email"

    @model_validator(mode="after")
    def check_configuration(self: Self) -> Self:
        if (
            self.OAUTH_CLIENT_NAME not in ["google", "github", None]
            and self.OAUTH_OIDC_CONFIG_ENDPOINT is None
        ):
            raise ValueError(
                f"self.OAUTH_OIDC_CONFIG_ENDPOINT=None but "
                f"{self.OAUTH_CLIENT_NAME=}"
            )
        return self

    @property
    def is_set(self) -> bool:
        return None not in (
            self.OAUTH_CLIENT_NAME,
            self.OAUTH_CLIENT_ID,
            self.OAUTH_CLIENT_SECRET,
        )

Minimal working example¶

This is a minimal working example of a .fractal_server.env, with all the required configuration variables set:

JWT_SECRET_KEY=secret-key-for-jwt-tokens
POSTGRES_DB=fractal-database-name

These are the only required variables. All others, if not specified, will assume their default value.

Configuration

Set configuration variables¶

Get current configuration¶

Configuration variables¶

Settings ¶

DatabaseSettings ¶

EmailSettings ¶

OAuthSettings ¶

Minimal working example¶

`Settings` ¶

`DatabaseSettings` ¶

`EmailSettings` ¶

`OAuthSettings` ¶