5 ‐ Central Server Configuration - Bento-Project-SCARS/ProjectSCARS GitHub Wiki

Reference: config.json

This configuration file is used for the central server. Below is a detailed description of each section in the configuration.

{
    "ai": {
        "enabled": false,
        "gemini_api_key": "your-gemini-api-key-here",
        "gemini_model": "gemini-2.5-flash-lite-preview-06-17"
    },
    "debug": {
        "enabled": false,
        "logenv_optout": true,
        "show_sql": false,
        "hot_reload": false
    },
    "connection": {
        "host": "0.0.0.0",
        "port": 8081,
        "base_url": "http://localhost:8080"
    },
    "logging": {
        "file_logging_enabled": true,
        "filepath": "./logs/centralserver.log",
        "max_bytes": 10485760,
        "backup_count": 5,
        "encoding": "utf-8",
        "log_format": "%(asctime)s:%(name)s:%(levelname)s:%(message)s",
        "date_format": "%d-%m-%y_%H-%M-%S"
    },
    "database": {
        "type": "sqlite",
        "config": {
            "filepath": "./db/centralserver.db"
        }
    },
    "object_store": {
        "type": "local",
        "config": {
            "max_file_size": 2097152,
            "min_image_size": 256,
            "allowed_image_types": ["png", "jpeg", "jpg", "webp"],
            "filepath": "./data/"
        }
    },
    "authentication": {
        "signing_secret_key": "UPDATE_THIS_VALUE",
        "refresh_signing_secret_key": "UPDATE_THIS_VALUE",
        "encryption_secret_key": "UPDATE_THIS_VALUE",
        "signing_algorithm": "HS256",
        "encryption_algorithm": "A256GCM",
        "encrypt_jwt": true,
        "access_token_expire_minutes": 30,
        "refresh_token_expire_minutes": 129600,
        "recovery_token_expire_minutes": 15,
        "otp_nonce_expire_minutes": 5,
        "oauth": {
            "google": {
                "client_id": "UPDATE_THIS_VALUE",
                "client_secret": "UPDATE_THIS_VALUE",
                "redirect_uri": "http://localhost:8080/login/oauth/google"
            }
        }
    },
    "security": {
        "allow_origins": ["http://127.0.0.1:8080", "http://localhost:8080"],
        "allow_credentials": true,
        "allow_methods": ["*"],
        "allow_headers": ["*"],
        "failed_login_lockout_attempts": 5,
        "failed_login_notify_attempts": 2,
        "failed_login_lockout_minutes": 15
    },
    "mailing": {
        "enabled": false,
        "server": "smtp.example.com",
        "port": 587,
        "from_address": "",
        "username": "",
        "password": "",
        "templates_dir": "./templates/mail/",
        "templates_encoding": "utf-8"
    }
}

1. ai

"ai": {
    "enabled": false,
    "gemini_api_key": "your-gemini-api-key-here",
    "gemini_model": "gemini-2.5-flash-lite-preview-06-17"
}

Contains information about features that utilize artificial intelligence. Currently, the system only supports Google Gemini.

Key Type Description
enabled bool If True, AI features are enabled.
gemini_api_key string The API key to use when connecting to Google Gemini.
gemini_model string The model to use when communicating with Google Gemini.

2. debug

"debug": {
    "enabled": false,
    "logenv_optout": true,
    "show_sql": false,
    "hot_reload": false
}

Controls the debugging features of the application. These settings are primarily for development purposes.

Key Type Description
enabled bool Enables or disables debug mode. (default: False)
logenv_optout bool If True, environment variables are not logged to prevent potential security/privacy risks (default: True).
show_sql bool Logs SQL queries when enabled (default: False).
hot_reload bool Enables the --reload option of uvicorn, automatically restarting the server on code changes (default: False).

3. connection

Defines the connection details for the central server.

"connection": {
    "host": "0.0.0.0",
    "port": 8081,
    "base_url": "http://localhost:8080",
    "gemini_api_key": "YOUR_GEMINI_API_KEY"
}
Key Type Description
host string The host address where the server listens. Set to 0.0.0.0 by default to allow connections from any network interface.
port integer The port on which the server listens (default: 8081).
base_url string The external URL of the frontend/web client (e.g., http://localhost:8080).
gemini_api_key string The API key for Google Gemini (AI Chat)

4. logging

Configures the logging system.

"logging": {
    "file_logging_enabled": true,
    "filepath": "./logs/centralserver.log",
    "max_bytes": 10485760,
    "backup_count": 5,
    "encoding": "utf-8",
    "log_format": "%(asctime)s:%(name)s:%(levelname)s:%(message)s",
    "date_format": "%d-%m-%y_%H-%M-%S"
}
Key Type Description
file_logging_enabled bool If set to false, do not save the logs to file. filepath, max_bytes, and backup_count are ignored.
filepath string The path to the log file where server logs will be stored (default: ./logs/centralserver.log).
max_bytes integer The maximum file size (in bytes) before creating a new log file. Default is 10485760 (10 MB).
backup_count integer The number of backup log files to keep before overwriting old ones. Default is 5.
encoding string The encoding used for the log files (default: utf-8).
log_format string The format of the log messages. Uses Python's logging format. Default is %(asctime)s:%(name)s:%(levelname)s:%(message)s.
date_format string The format for date/time in the log entries. Default is "%d-%m-%y_%H-%M-%S".

5. database

Defines the database configuration for the application. The system currently supports the following databases:

The database type is specified in the configuration file, and each type has a specific configuration schema.

SQLite Database

SQLite is a self-contained, serverless database engine, which stores data in a single file. It's well-suited for development or lightweight applications.

{
    /* ... */
    "database": {
        "type": "sqlite",
        "config": {
            "filepath": "database.db",
            "connect_args": {
                // SQLAlchemy connection arguments
            }
        }
    }
    /* ... */
}
Key Type Description
type string The database type, set to "sqlite" for SQLite.
config object Configuration specific to the SQLite database.
config.filepath string The path to the SQLite database file.
config.connect_args object Optional additional connection arguments for SQLAlchemy.

MySQL Database

MySQL is a widely-used relational database management system that offers scalability, flexibility, and ease of use.

{
    /* ... */
    "database": {
        "type": "mysql",
        "config": {
            "username": "ProjectSCARS_DatabaseAdmin",
            "password": "ProjectSCARS_mysql143",
            "host": "localhost",
            "port": 3306,
            "database": "ProjectSCARS_CentralServer",
            "connect_args": {
                // sqlalchemy connection arguments
            }
        }
    }
    /* ... */
}
Key Type Description
type string The database type, set to "mysql" for MySQL.
config object Configuration specific to the MySQL database.
config.username string The MySQL username.
config.password string The password for the MySQL user.
config.host string The hostname or IP address of the MySQL server.
config.port integer The port for MySQL (default: 3306).
config.database string The name of the database to use.
config.connect_args object Optional additional connection arguments for SQLAlchemy.

PostgreSQL Database

PostgreSQL is an open-source, object-relational database system known for its robustness, flexibility, and compliance with SQL standards.

{
    /* ... */
    "database": {
        "type": "postgres",
        "config": {
            "username": "ProjectSCARS_DatabaseAdmin",
            "password": "ProjectSCARS_postgres143",
            "host": "localhost",
            "port": 5432,
            "database": "ProjectSCARS_CentralServer",
            "connect_args": {
                // sqlalchemy connection arguments
            }
        }
    }
    /* ... */
}
Key Type Description
type string The database type, set to "postgres" for PostgreSQL.
config object Configuration specific to the PostgreSQL database.
config.username string The PostgreSQL username.
config.password string The password for the PostgreSQL user.
config.host string The hostname or IP address of the PostgreSQL server.
config.port integer The port for PostgreSQL (default: 5432).
config.database string The name of the database to use.
config.connect_args object Optional additional connection arguments for SQLAlchemy.

6. object_store

Configures the object storage system used to store files. These are used to store files such as images, exported reports, and other media. The system currently supports the following object stores:

[!WARNING]

All object store adapters have the following settings:

"config": {
    "max_file_size": 2097152,
    "min_image_size": 256,
    "allowed_image_types": ["png", "jpeg", "jpg", "webp"],
    /* ... */
}
Key Type Description
max_file_size integer The maximum avatar file size the central server will accept.
min_image_size integer The minimum pixel size of the avatar to accept.
allowed_image_types array A list of allowed filetypes to be used as avatar.

Local Object Store

The local object storage is a pure-Python implementation of the object store that allows you to store files on the server's local filesystem.

{
    /* ... */
    "object_store": {
        "type": "local",
        "config": {
            "filepath": "./data/"
        }
    }
    /* ... */
}
Key Type Description
type string The object store type, set to "local" for local storage.
config object Configuration specific to local storage.
config.filepath string The path where files will be stored.

MinIO Object Store

MinIO is an open-source object storage server compatible with the Amazon S3 API. It can be used as a self-hosted alternative to S3 for managing large amounts of unstructured data.

{
    /* ... */
    "object_store": {
        "type": "minio",
        "config": {
            "endpoint": "localhost:9000",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "secure": false
        }
    }
    /* ... */
}
Key Type Description
type string The object store type, set to "minio" for MinIO.
config object Configuration specific to MinIO storage.
config.endpoint string The endpoint of the MinIO server (e.g., localhost:9000).
config.access_key string The access key for MinIO authentication.
config.secret_key string The secret key for MinIO authentication.
config.secure bool Whether to use HTTPS (default: false).

Garage Object Store

Garage is a distributed object storage system. It provides an alternative to MinIO, typically used in larger enterprise systems for managing object data at scale.

{
    /* ... */
    "object_store": {
        "type": "garage",
        "config": {
            "endpoint": "localhost:3900",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "secure": false
        }
    }
    /* ... */
}
Key Type Description
type string The object store type, set to "garage" for Garage storage.
config object Configuration specific to Garage storage.
config.endpoint string The endpoint of the Garage server (e.g., localhost:3900).
config.access_key string The access key for Garage authentication.
config.secret_key string The secret key for Garage authentication.
config.secure bool Whether to use HTTPS (default: false).

7. authentication

Configures authentication settings, including OAuth integration and token expiration times.

"authentication": {
    "signing_secret_key": "UPDATE_THIS_VALUE",
    "refresh_signing_secret_key": "UPDATE_THIS_VALUE",
    "encryption_secret_key": "UPDATE_THIS_VALUE",
    "signing_algorithm": "HS256",
    "encryption_algorithm": "A256GCM",
    "encrypt_jwt": true,
    "access_token_expire_minutes": 30,
    "refresh_token_expire_minutes": 129600,
    "recovery_token_expire_minutes": 15,
    "otp_nonce_expire_minutes": 5,
    "oauth": {
        // ...
    }
}
Key Type Description
signing_secret_key string The secret key used to sign JWT tokens (to be generated manually).
refresh_signing_secret_key string The secret key used to sign refresh tokens (to be generated manually).
encryption_secret_key string The key used for token encryption (to be generated manually).
signing_algorithm string The algorithm used to sign JWT tokens (default: HS256).
encryption_algorithm string The algorithm used for token encryption (default: A256GCM).
encrypt_jwt bool Whether to return the access token as a JWT (False) or JWE (True).
access_token_expire_minutes integer Expiry time of the access token in minutes (default: 30).
refresh_token_expire_minutes integer Expiry time of the refresh token in minutes (default: 129600 - 90 days).
recovery_token_expire_minutes integer Expiry time of the recovery token in minutes (default: 15).
otp_nonce_expire_minutes integer Expiry time for OTP nonces in minutes (default: 5).
oauth object OAuth provider configurations (Google, Microsoft, Facebook). See Open Authentication

Open Authentication

OAuth is used for third-party authentication (e.g., login via Google, Microsoft, or Facebook). The system currently supports Google OAuth, with support for Microsoft and Facebook OAuth planned for future releases.

Google OAuth

Google OAuth allows users to authenticate via their Google accounts.

{
    /* ... */
    "authentication": {
        "oauth": {
            "google": {
                "client_id": "UPDATE_THIS_VALUE",
                "client_secret": "UPDATE_THIS_VALUE",
                "redirect_uri": "http://localhost:8080/login/oauth/google"
            }
        }
    }
    /* ... */
}
Key Type Description
client_id string The client ID obtained from the Google Developer Console.
client_secret string The client secret obtained from the Google Developer Console.
redirect_uri string The URI to redirect to after successful authentication. The path /login/oauth/google is fixed, but the domain and port are configurable.

Microsoft OAuth (Planned)

Support for Microsoft OAuth will be added in future releases. The configuration will be similar to the Google OAuth configuration.

8. security

Security settings related to CORS, login lockouts, and failed login attempts.

"security": {
    "allow_origins": ["http://127.0.0.1:8080", "http://localhost:8080"],
    "allow_credentials": true,
    "allow_methods": ["*"],
    "allow_headers": ["*"],
    "failed_login_lockout_attempts": 5,
    "failed_login_notify_attempts": 2,
    "failed_login_lockout_minutes": 15
}
Key Type Description
allow_origins array List of allowed origins for CORS (supports wildcards).
allow_credentials bool Whether to allow credentials in CORS requests (default: true).
allow_methods array List of allowed HTTP methods in CORS (default: ["*"]).
allow_headers array List of allowed headers in CORS (default: ["*"]).
failed_login_lockout_attempts integer The number of failed login attempts before the account is locked.
failed_login_notify_attempts integer The number of failed login attempts before notifying admins.
failed_login_lockout_minutes integer The duration (in minutes) of the lockout after failed attempts.

9. mailing

Configures the email service. If disabled, account recovery emails are logged instead of being sent.

"mailing": {
    "enabled": false,
    "server": "smtp.example.com",
    "port": 587,
    "from_address": "",
    "username": "",
    "password": "",
    "templates_dir": "./templates/mail/",
    "templates_encoding": "utf-8"
}
Key Type Description
enabled bool Whether mailing is enabled. If disabled, email content is logged.
server string The SMTP server address for sending emails.
port integer The port of the SMTP server (default: 587).
from_address string The sender’s email address (e.g., [email protected]).
username string The username for SMTP authentication.
password string The password for SMTP authentication.
templates_dir string The directory where email templates are stored.
templates_encoding string The encoding for email templates (default: utf-8).

Additional Notes

  • Key Generation: Use the script ./scripts/secret.py to generate secure keys for JWT signing and encryption. Run it with the sign, secret, or refresh argument to generate each key. You can specify the configuration file path using the -c/--config argument.
  • OAuth: Currently, only Google OAuth is implemented. Future versions will include Microsoft OAuth support.