Configuration

Configuration module for application settings.

Environment Variables (.env)

The application configuration is managed through environment variables loaded from a .env file located in the backend/app/ directory.

Configuration File Structure

Create a .env file in backend/app/ with the following structure:

# --- Database Section (Prefix: DB_) ---
DB_URL=mongodb://localhost:27017/
DB_NAME=ddfr_db
DB_COLLECTION=people
DB_HASH="300a31fbdc6f3ff4fb27625c2ed49fdc"

# --- Logging Section (Prefix: LOG_) ---
LOG_LOGFOLDER=logs

# --- API Section (Prefix: APP_) ---
APP_NAME=DDFR API
APP_VERSION=1.0.0
APP_DESCRIPTION=API for face recognition and person management
APP_TOLLERANCE=0.5
APP_DEBUG=false
APP_HOST=0.0.0.0
APP_PORT=8000
APP_USE_HTTPS=false
APP_KEYPATH=
APP_CERTPATH=

Variable Descriptions

Database Settings (Prefix: `DB_`)

DB_URL (string): MongoDB connection URL.
Default: "mongodb://localhost:27017/"
Example: "mongodb+srv://user:password@cluster.mongodb.net/"
DB_NAME (string): Database name.
Default: "ddfr_db"
DB_COLLECTION (string): MongoDB collection name for storing person data.
Default: "people"
DB_HASH (string): Legacy hash value (currently not actively used, kept for backward compatibility).
Value: "300a31fbdc6f3ff4fb27625c2ed49fdc"

Logging Settings (Prefix: `LOG_`)

LOG_LOGFOLDER (string): Directory path for log files. If not specified, defaults to logs-{timestamp} in the backend directory.
Example: "logs" or "C:/logs/ddfr"

API Settings (Prefix: `APP_`)

APP_NAME (string): Application name displayed in API documentation.
Default: "DDFR API"
APP_VERSION (string): Application version.
Default: "1.0.0"
APP_DESCRIPTION (string): Application description displayed in API documentation.
Default: "API for face recognition and person management"
APP_TOLLERANCE (float): Face recognition similarity threshold (0.0-1.0). Lower values are more strict.
Default: 0.5
Recommended range: 0.4-0.6
⚠️ Deprecated: This setting is being phased out and used less frequently. Consider using hardcoded thresholds in the recognition service instead.
APP_DEBUG (boolean): Enable debug mode. When enabled, provides more verbose logging.
Default: false
Values: true or false
APP_HOST (string): Server host address to bind to.
Default: "0.0.0.0" (listens on all interfaces)
For localhost only: "127.0.0.1"
APP_PORT (integer): Server port number.
Default: 8000
APP_USE_HTTPS (boolean): Enable HTTPS support.
Default: false
Values: true or false
APP_KEYPATH (string, optional): Path to SSL private key file (required if APP_USE_HTTPS=true).
Default: None (empty)
Example: "C:/path/to/key.pem" (Windows) or "/path/to/key.pem" (Mac/Linux)
APP_CERTPATH (string, optional): Path to SSL certificate file (required if APP_USE_HTTPS=true).
Default: None (empty)
Example: "C:/path/to/cert.pem" (Windows) or "/path/to/cert.pem" (Mac/Linux)

Creating SSL Certificates

To enable HTTPS, you need to generate SSL certificates. Here are some common approaches:

Using mkcert (Recommended for Development)

mkcert is a simple tool for making locally-trusted development certificates:

Install mkcert:
Windows: choco install mkcert or download from GitHub releases
macOS: brew install mkcert
Linux: See installation instructions
Install the local CA:
```
mkcert -install
```
Generate certificate for your domain:
```
mkcert ddfr.local localhost 127.0.0.1 ::1
```
This creates ddfr.local+2.pem (certificate) and ddfr.local+2-key.pem (private key)

Update your .env file:

APP_USE_HTTPS=true
APP_KEYPATH=/path/to/ddfr.local+2-key.pem
APP_CERTPATH=/path/to/ddfr.local+2.pem

Using OpenSSL (Manual)

For manual certificate generation using OpenSSL:

Generate a private key:
```
openssl genrsa -out key.pem 2048
```

Create a certificate signing request (CSR):

openssl req -new -key key.pem -out csr.pem

Generate a self-signed certificate:

openssl x509 -req -days 365 -in csr.pem -signkey key.pem -out cert.pem

Note: Self-signed certificates will show security warnings in browsers. For production, use certificates from a trusted Certificate Authority (CA).

Production Certificates

For production environments, consider: - Let's Encrypt: Free, automated SSL certificates - https://letsencrypt.org/ - Cloudflare: Provides free SSL certificates for proxied domains - Commercial CAs: Various providers offer SSL certificates (DigiCert, GlobalSign, etc.)

Additional Resources

Configuration Classes

DatabaseSettings

app.config.DatabaseSettings

Bases: BaseSettings

Database connection configuration settings for MongoDB.

Loads settings from .env file using the "DB_" prefix. All environment variables must be prefixed with DB_ to be recognized.

Attributes:

Name	Type	Description
`url`	`str`	MongoDB connection URL. Default: "mongodb://localhost:27017/".
`name`	`str`	Database name. Default: "ddfr_db".
`collection`	`str`	MongoDB collection name. Default: "people".
`hash`	`str`	Hash for data security. Required, no default value.

Source code in backend/app/config.py

class DatabaseSettings(BaseSettings):
    """Database connection configuration settings for MongoDB.

    Loads settings from .env file using the "DB_" prefix.
    All environment variables must be prefixed with DB_ to be recognized.

    Attributes:
        url (str): MongoDB connection URL. Default: "mongodb://localhost:27017/".
        name (str): Database name. Default: "ddfr_db".
        collection (str): MongoDB collection name. Default: "people".
        hash (str): Hash for data security. Required, no default value.

    """

    url: str = "mongodb://localhost:27017/"
    name: str = "ddfr_db"
    collection: str = "people"
    hash: str 

    class Config:
        env_prefix = "DB_"
        env_file = ENV_FILE_PATH
        env_file_encoding = 'utf-8'
        extra = "ignore"

PathSettings

app.config.PathSettings

Bases: BaseSettings

File system path configuration settings.

Loads settings from .env file using the "LOG_" prefix. All environment variables must be prefixed with LOG_ to be recognized.

Attributes:

Name	Type	Description
`logfolder`	`str`	Directory path for log files. Default: "logs-{timestamp}" in backend directory.
`imgsfolder`	`str`	Directory path for image storage. Default: "img" in app directory.

Source code in backend/app/config.py

class PathSettings(BaseSettings):
    """File system path configuration settings.

    Loads settings from .env file using the "LOG_" prefix.
    All environment variables must be prefixed with LOG_ to be recognized.

    Attributes:
        logfolder (str): Directory path for log files. Default: "logs-{timestamp}" in backend directory.
        imgsfolder (str): Directory path for image storage. Default: "img" in app directory.

    """

    logfolder: str = os.path.join(BACKEND_DIR, f"logs-{_STARTUP_TIMESTAMP}")
    imgsfolder: str = os.path.join(BASE_DIR, "img")

    class Config:
        env_prefix = "LOG_"
        env_file = ENV_FILE_PATH
        env_file_encoding = 'utf-8'
        extra = "ignore"

APISettings

app.config.APISettings

Bases: BaseSettings

API application configuration settings.

Loads settings from .env file using the "APP_" prefix. All environment variables must be prefixed with APP_ to be recognized.

Attributes:

Name	Type	Description
`host`	`str`	API server host address. Default: "192.168.1.69".
`port`	`int`	API server port number. Default: 8000.
`app_name`	`str`	Application name. Default: "DDFR API".
`description`	`str`	API description. Default: "API per il riconoscimento facciale e la gestione delle persone".
`app_version`	`str`	Application version. Default: "1.0.0".
`tollerance`	`float`	Face recognition tolerance threshold. Default: 0.5.
`debug`	`bool`	Enable debug mode. Default: False.
`use_https`	`bool`	Enable HTTPS. Default: False.
`keypath`	`Optional[str]`	Path to SSL private key file. Default: None.
`certpath`	`Optional[str]`	Path to SSL certificate file. Default: None.

Source code in backend/app/config.py

class APISettings(BaseSettings):
    """API application configuration settings.

    Loads settings from .env file using the "APP_" prefix.
    All environment variables must be prefixed with APP_ to be recognized.

    Attributes:
        host (str): API server host address. Default: "192.168.1.69".
        port (int): API server port number. Default: 8000.
        app_name (str): Application name. Default: "DDFR API".
        description (str): API description. Default: "API per il riconoscimento facciale e la gestione delle persone".
        app_version (str): Application version. Default: "1.0.0".
        tollerance (float): Face recognition tolerance threshold. Default: 0.5.
        debug (bool): Enable debug mode. Default: False.
        use_https (bool): Enable HTTPS. Default: False.
        keypath (Optional[str]): Path to SSL private key file. Default: None.
        certpath (Optional[str]): Path to SSL certificate file. Default: None.

    """

    host: str = "192.168.1.69"
    port: int = 8000
    app_name: str = "DDFR API"
    description: str = "API per il riconoscimento facciale e la gestione delle persone"
    app_version: str = "1.0.0"
    tollerance: float = 0.5
    debug: bool = False
    use_https: bool = False
    keypath: Optional[str] = None
    certpath: Optional[str] = None

    class Config:
        env_prefix = "APP_"
        env_file = ENV_FILE_PATH
        env_file_encoding = 'utf-8'
        extra = "ignore"

Configuration

Environment Variables (.env)

Configuration File Structure

Variable Descriptions

Database Settings (Prefix: DB_)

Logging Settings (Prefix: LOG_)

API Settings (Prefix: APP_)

Creating SSL Certificates

Using mkcert (Recommended for Development)

Using OpenSSL (Manual)

Production Certificates

Additional Resources

Configuration Classes

DatabaseSettings

app.config.DatabaseSettings

PathSettings

app.config.PathSettings

APISettings

app.config.APISettings

Database Settings (Prefix: `DB_`)

Logging Settings (Prefix: `LOG_`)

API Settings (Prefix: `APP_`)