v1.0.0

Configuration

Clientra CRM uses PHP configuration files stored outside the web root for security. This page documents all configuration files, their options, and the in-app settings available through the Settings page.

❌ Never Commit config/ to Git
The config/ directory contains sensitive credentials and encryption keys. Add it to your .gitignore and never commit it to version control.

Database Configuration — config/db.php

The database configuration file is created automatically by the installation wizard. You can edit it manually if credentials change.

php
<?php
// config/db.php — Database connection settings
return [
    'host'     => 'localhost',        // DB host (usually localhost)
    'dbname'   => 'invejrek_crmmain', // Database name
    'username' => 'db_user',          // DB username
    'password' => 'db_password',      // DB password
    'charset'  => 'utf8mb4',          // Always use utf8mb4
    'options'  => [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE  => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES    => false,
    ],
];
KeyTypeDescription
hoststringDatabase server hostname. Use localhost for local MySQL, or a remote IP/hostname.
dbnamestringDatabase name. Must exist before installation.
usernamestringMySQL user with full privileges on the database.
passwordstringMySQL user password.
charsetstringAlways utf8mb4 for full Unicode support including emoji.
optionsarrayPDO driver options. Do not change unless you know what you're doing.

Secrets Configuration — config/secrets.php

Contains the application encryption key and other sensitive settings. This file is auto-generated during installation.

❌ Do NOT Regenerate app_key
The app_key is used to encrypt email account passwords stored in the database. If you change or regenerate it, all existing encrypted passwords become unreadable and email accounts will stop working.
php
<?php
// config/secrets.php — Application secrets
return [
    // 256-bit encryption key — DO NOT change after database has data
    'app_key' => 'base64:your_256_bit_key_here...',

    // Session save path (absolute path)
    'session_path' => '/home/user/clientra/config/sessions',

    // Rate limiting (requests per minute per IP)
    'rate_limit' => [
        'enabled'  => true,
        'requests' => 120,     // Max requests per window
        'window'   => 60,      // Window in seconds
    ],

    // CORS allowed origins (set to your domain)
    'cors_origins' => [
        'https://yourdomain.com',
        'https://www.yourdomain.com',
    ],

    // JWT settings (for API/Webhook addon)
    'jwt' => [
        'secret'  => 'your_jwt_secret',
        'expire'  => 3600,  // Token expiry in seconds
        'issuer'  => 'clientra-crm',
    ],
];

Application Settings

In-app settings are managed through the Settings page (admin only) and stored in the app_settings database table. These can be changed at any time without restarting the server.

General Settings

SettingDefaultDescription
App NameClientra CRMDisplayed in the browser title, sidebar, and PDF headers
Primary Color#3B82F6Hex color used for buttons, highlights, and accents
ThemedarkDefault UI theme for new users. Each user can override this.
LanguageenInterface language (English only in current version)
CurrencyAEDCurrency symbol used throughout the app
Date FormatDD/MM/YYYYDate display format
TimezoneAsia/DubaiServer timezone for timestamps
Text SizemediumBase font size (small / medium / large)

Storage Settings

SettingOptionsDescription
Storage Typelocal / wasabiWhere uploaded files are stored
Wasabi BucketstringS3 bucket name (Wasabi only)
Wasabi Regionstringe.g., us-east-1
Wasabi Access KeystringWasabi access key ID
Wasabi Secret KeystringWasabi secret access key
Wasabi EndpointURLe.g., https://s3.wasabisys.com

Email Configuration

Email accounts are managed through Settings → Email Accounts. Multiple accounts can be added with per-user permissions.

json
{
  "account_name": "Company Email",
  "email": "info@company.com",

  "imap_host": "mail.company.com",
  "imap_port": 993,
  "imap_encryption": "ssl",    // ssl | tls | none
  "imap_username": "info@company.com",
  "imap_password": "encrypted_at_rest",

  "smtp_host": "mail.company.com",
  "smtp_port": 587,
  "smtp_encryption": "tls",    // ssl | tls | none
  "smtp_username": "info@company.com",
  "smtp_password": "encrypted_at_rest"
}
ℹ Password Encryption
Email passwords are encrypted using the app_key from config/secrets.php before storage. This is why the app_key must never be changed after email accounts have been configured.

Cache Busting

Since there is no build step, JavaScript files must be manually versioned when modified to ensure browsers load the latest code.

⚠ Always Increment Version After Editing JS
When you edit any JavaScript file, find its <script> tag in public/index.php and increment the ?v= parameter.
html
<!-- Before editing: -->
<script src="assets/js/pages/Leads.js?v=2.3"></script>

<!-- After editing (minor change): -->
<script src="assets/js/pages/Leads.js?v=2.4"></script>

<!-- After major refactor: -->
<script src="assets/js/pages/Leads.js?v=3.0"></script>

Version Numbering Convention

Change TypeIncrementExample
Minor bug fix or small changePatch (0.0.X)2.3 → 2.4
New feature or significant changeMinor (0.X.0)2.3 → 3.0
Major refactor or full rewriteMajor (X.0.0)2.3 → 3.0

Session Configuration

php
// Session settings (set early in bootstrap)
ini_set('session.save_path', $config['session_path']);
ini_set('session.gc_maxlifetime', 86400);  // 24 hours
ini_set('session.cookie_httponly', 1);
ini_set('session.cookie_samesite', 'Lax');
ini_set('session.cookie_secure', 1);   // HTTPS only
session_name('clientra_session');
ℹ Sessions Directory Permissions
Ensure the sessions directory is writable by the web server user: chmod 700 config/sessions/. The directory should not be web-accessible (it's outside the document root, so it shouldn't be by default).