Skip to main content

System Configuration

OmniCRM uses two main configuration systems: crm_config.yaml for backend API settings and environment variables for the React UI. This guide covers all configuration options and how to modify them.

Configuration Files Overview​

Backend API Configuration:

  • File: OmniCRM-API/crm_config.yaml
  • Format: YAML
  • Requires: API restart after changes
  • Used for: Database, integrations, security, provisioning

Frontend UI Configuration:

  • File: OmniCRM-UI/.env
  • Format: Environment variables
  • Requires: UI rebuild after changes
  • Used for: Branding, features, external services

Backend Configuration (crm_config.yaml)​

The crm_config.yaml file contains all backend system settings.

Database Configuration​

database:
  username: omnitouch
  password: omnitouch2024
  server: localhost

Fields:

  • username - MySQL database username
  • password - MySQL database password
  • server - Database server hostname or IP (default: localhost)

Database Connection:

  • Database name is hardcoded as omnicrm
  • Default port: 3306 (MySQL default)
  • Connection string: mysql+pymysql://username:password@server/omnicrm

Security Note: Never commit this file with real credentials to version control. Use environment-specific configuration or secrets management.

Service Types​

service_types:
  - omnicharge
  - mobile
  - internet
  - iptv
  - voip

Purpose: Defines valid service type values for the service_type field.

Default Types:

  • mobile - Mobile/cellular services
  • internet - Fixed internet (fiber, DSL, wireless)
  • iptv - Television services
  • voip - Voice-over-IP services
  • omnicharge - Billing/charging services

Add custom service types here for your specific use cases.

HSS (Home Subscriber Server) Configuration​

hss:
  hss_peers:
    - 'http://10.179.2.140:8080'
  apn_list: "1,2,3,4,5,6"

Fields:

  • hss_peers - List of HSS server URLs for subscriber management
  • apn_list - Comma-separated list of APN (Access Point Name) identifiers

Used for: Mobile network provisioning and subscriber authentication.

Mailjet Email Configuration​

mailjet:
  api_key: your_mailjet_api_key
  api_secret: your_mailjet_api_secret

  api_crmCommunicationCustomerWelcome:
    from_email: "support@yourcompany.com"
    from_name: "Your Company Support"
    template_id: 5977509
    subject: "Welcome to Your Company"

  api_crmCommunicationCustomerInvoice:
    from_email: "billing@yourcompany.com"
    from_name: "Your Company Billing"
    template_id: 6759851
    subject: "Your Invoice - "

Email Types Configured:

  • api_crmCommunicationCustomerWelcome - New customer welcome email
  • api_crmCommunicationCustomerInvoice - Invoice delivery
  • api_crmCommunicationCustomerInvoiceReminder - Overdue invoice reminders
  • api_crmCommunicationUserWelcome - New staff user welcome
  • api_crmCommunicationUserPasswordReset - Password reset requests
  • api_crmCommunicationUserPasswordResetSuccess - Successful password reset
  • api_crmCommunicationUserPasswordChange - Password change notifications
  • api_crmCommunicationEmailVerification - Email address verification
  • api_crmCommunicationsBalanceExpired - Service expiry notifications
  • api_crmCommunicationsBalanceLow - Low balance alerts

Template IDs:

Obtain from your Mailjet account after creating email templates. See integrations_mailjet for details.

Provisioning Configuration​

provisioning:
  failure_list: ['admin@yourcompany.com', 'ops@yourcompany.com']

Fields:

  • failure_list - Email addresses to notify when provisioning fails

When Ansible playbooks fail during provisioning, the system sends error details to these addresses.

Invoice Configuration​

invoice:
  template_filename: 'your_invoice_template.html'

Fields:

  • template_filename - HTML template file for invoice generation

Template file should exist in OmniCRM-API/templates/ directory.

CRM Base URL​

crm:
  base_url: 'http://localhost:5000'

Purpose: Used by Ansible playbooks to make API calls back to the CRM.

Important:

  • Do NOT include trailing slash
  • Use publicly accessible URL if playbooks run on different servers
  • Update when deploying to production (e.g., https://api.yourcrm.com)

OCS (Online Charging System) Configuration​

ocs:
  ocsApi: 'http://10.179.2.142:8080/api'
  ocsTenant: 'mnc380.mcc313.3gppnetwork.org'
  cgrates: 'localhost:2080'

Fields:

  • ocsApi - OCS REST API endpoint URL
  • ocsTenant - Tenant identifier for multi-tenant OCS deployments
  • cgrates - CGRateS JSON-RPC endpoint (host:port)

Used for: Real-time charging, balance management, usage tracking.

SMSC (SMS Center) Configuration​

smsc:
  source_msisdn: 'YourCompany'
  smsc_url: 'http://10.179.2.216/SMSc/'
  api_key: 'your_smsc_api_key'

Fields:

  • source_msisdn - Sender ID for outbound SMS (company name or short code)
  • smsc_url - SMS Center API endpoint
  • api_key - Authentication key for SMSC API

Used for: Sending SMS notifications (balance alerts, OTPs, etc.)

Cell Broadcast Configuration​

cbc_url: 'http://10.179.1.113:8080'

Purpose: Cell Broadcast Center (CBC) API endpoint for emergency alerts.

See features_cell_broadcast for usage details.

JWT Secret Key​

jwt_secret: '2b93110f723db60172c8e9a1eaa80027a9a9c3f05b44e50dc3fcf38dba68d87e'

Purpose: Secret key for signing JWT authentication tokens.

Security:

  • Generate using: openssl rand -hex 32
  • Never share publicly
  • Changing this invalidates all existing user sessions
  • Use different secrets for dev/staging/production

Stripe Payment Configuration​

stripe:
  secret_key: 'sk_test_...'
  publishable_key: 'pk_test_...'
  currency: 'usd'
  statement_descriptor_suffix: 'YOURCOMPANY'

Fields:

  • secret_key - Stripe secret API key (starts with sk_)
  • publishable_key - Stripe publishable key (starts with pk_)
  • currency - ISO 4217 currency code (usd, gbp, aud, eur, etc.)
  • statement_descriptor_suffix - Text appearing on customer credit card statements

Key Types:

  • Test keys: sk_test_... and pk_test_... (for development)
  • Live keys: sk_live_... and pk_live_... (for production)

See integrations_stripe for setup details.

API Keys​

api_keys:
  "your-secure-api-key-minimum-32-chars":
    roles: ["admin"]
    ips: ["127.0.0.1", "::1"]
  "another-api-key-for-specific-service":
    roles: ["customer_service_agent_1"]
    ips: ["10.0.1.50"]

Structure:

  • Key (string): The actual API key (minimum 32 characters)
  • roles (list): Role names this key has access to
  • ips (list, optional): IP addresses allowed to use this key

Generating API Keys:

openssl rand -base64 48

Roles:

  • admin - Full access to all endpoints
  • Custom roles defined in RBAC system

See administration_api_keys and concepts_api for details.

IP Whitelist​

ip_whitelist:
  "10.179.2.142":
    roles: ["admin"]
  "192.168.1.100":
    roles: ["provisioning"]

Purpose: Allow specific IP addresses to access the API without authentication.

Structure:

  • IP Address (string): IPv4 address to whitelist
  • roles (list): Roles assigned to requests from this IP

Security Warning:

  • Only use for trusted internal networks
  • Must NOT use localhost IPs (127.0.0.1, ::1)
  • Use API keys instead for external access
  • Consider firewall rules as additional protection

Frontend Configuration (.env)​

The React UI is configured via environment variables in OmniCRM-UI/.env.

Branding Configuration​

REACT_APP_COMPANY_NAME="YourCompany"
REACT_APP_PORTAL_NAME="YourPortal"
REACT_APP_SELF_CARE_NAME="YourCare"
REACT_APP_COMPANY_TAGLINE="Your Company Slogan"

Fields:

  • REACT_APP_COMPANY_NAME - Company name (appears in headers, emails, branding)
  • REACT_APP_PORTAL_NAME - Admin portal name (page titles, navigation)
  • REACT_APP_SELF_CARE_NAME - Customer portal name
  • REACT_APP_COMPANY_TAGLINE - Marketing tagline (appears in login page)

Example:

Regional Configuration​

REACT_APP_DEFAULT_LOCATION="London, United Kingdom"
REACT_APP_DEFAULT_COUNTRY="United Kingdom"
REACT_APP_DEFAULT_LANGUAGE="en"
REACT_APP_LOCALE="en-GB"

Fields:

  • REACT_APP_DEFAULT_LOCATION - Default location for maps and addresses
  • REACT_APP_DEFAULT_COUNTRY - Default country for forms
  • REACT_APP_DEFAULT_LANGUAGE - UI language (ar, ch, en, fr, gr, it, ru, sp)
  • REACT_APP_LOCALE - Date/number formatting locale (en-GB, en-US, etc.)

Supported Languages:

  • ar - Arabic
  • ch - Chinese
  • en - English (default)
  • fr - French
  • gr - Greek
  • it - Italian
  • ru - Russian
  • sp - Spanish

Currency Configuration​

REACT_APP_CURRENCY_CODE="USD"
REACT_APP_CURRENCY_SYMBOL="$"

Fields:

  • REACT_APP_CURRENCY_CODE - ISO 4217 currency code
  • REACT_APP_CURRENCY_SYMBOL - Symbol to display (£, $, €, etc.)

Common Currencies:

  • USD - $ (US Dollar)
  • GBP - £ (British Pound)
  • EUR - € (Euro)
  • AUD - $ (Australian Dollar)
  • CAD - $ (Canadian Dollar)

Note: Must match stripe.currency in crm_config.yaml.

Color Theme Configuration​

REACT_APP_PRIMARY_COLOR=#405189
REACT_APP_SECONDARY_COLOR=#2bFFcf
REACT_APP_TERTIARY_COLOR=#1a9fbf

Available Colors:

  • REACT_APP_PRIMARY_COLOR - Main brand color (buttons, links, highlights)
  • REACT_APP_SECONDARY_COLOR - Accent color
  • REACT_APP_TERTIARY_COLOR - Additional accent
  • REACT_APP_SUCCESS_COLOR - Success messages (#28a745)
  • REACT_APP_INFO_COLOR - Info messages (#17a2b8)
  • REACT_APP_WARNING_COLOR - Warnings (#ffc107)
  • REACT_APP_DANGER_COLOR - Errors (#dc3545)
  • REACT_APP_LIGHT_COLOR - Light backgrounds (#f8f9fa)
  • REACT_APP_DARK_COLOR - Dark text (#343a40)
  • REACT_APP_PRIMARY_DARK_COLOR - Dark variant of primary color (for dark mode/hover states)

Format: Hexadecimal color codes (#RRGGBB)

Font Configuration​

REACT_APP_FONT_FAMILY=Quicksand

Purpose: Sets the primary font family for the entire UI.

Important: All fonts are self-hosted locally within the OmniCRM-UI application. This means:

  • No external font loading - Fonts are bundled with the application
  • Walled garden compatible - No internet access required for fonts to work
  • Offline operation - Full functionality in air-gapped or restricted network environments
  • Privacy - No external requests to Google Fonts, Adobe Fonts, or other CDNs
  • Performance - Faster loading without external dependencies
  • Security - No third-party tracking or data leakage through font requests

Available Options:

Sans-Serif Fonts:

  • Inter
  • Roboto
  • Open Sans
  • Lato
  • Quicksand (default)
  • Poppins
  • Nunito
  • Montserrat
  • Work Sans
  • Source Sans Pro
  • Raleway
  • Ubuntu
  • Josefin Sans
  • HKGrotesk

Serif Fonts:

  • Merriweather
  • Lora
  • Playfair Display

System Fonts:

  • System - Uses native device fonts for best performance and smallest bundle size

Default: Quicksand

Adding Custom Fonts​

Yes, you can add additional fonts! All fonts are stored locally in the application.

To add a new custom font:

  1. Add font files to OmniCRM-UI/src/assets/fonts/your-font-name/

    • Use WOFF2 format for best compression and browser support
    • Include multiple weights (300, 400, 500, 600, 700) for proper rendering
    • Name files: your-font-name-300.woff2, your-font-name-400.woff2, etc.

  2. Define @font-face rules in OmniCRM-UI/src/assets/scss/fonts/_google-fonts.scss

    //
    // Your Custom Font - Description
    //

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 400;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-400.woff2") format('woff2');
    }

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 700;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-700.woff2") format('woff2');
    }

  3. Set in .env file:

    REACT_APP_FONT_FAMILY=Your Font Name

Font Weight Guidelines:

  • 300 - Light (optional, for subtle headings)
  • 400 - Regular (required, default text)
  • 500 - Medium (optional, emphasis)
  • 600 - Semi-Bold (optional, subheadings)
  • 700 - Bold (required, headings and strong text)

Note: All fonts remain self-hosted and work offline. No external CDN or internet connection required.

External Services​

REACT_APP_GOOGLE_API_KEY=your_google_maps_api_key
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

Fields:

  • REACT_APP_GOOGLE_API_KEY - Google Maps API key (for maps, geolocation)
  • REACT_APP_STRIPE_PUBLISHABLE_KEY - Stripe publishable key (for payments)

Must Match:

REACT_APP_STRIPE_PUBLISHABLE_KEY must match stripe.publishable_key in crm_config.yaml.

REACT_APP_WEB_APP_1_NAME="GitHub"
REACT_APP_WEB_APP_1_URL="https://github.com"
REACT_APP_WEB_APP_1_ICON_PATH="resources/webapp_icons/github.png"

Purpose: Configure up to 6 quick-access web application links in the UI navigation.

Pattern:

  • REACT_APP_WEB_APP_N_NAME - Display name
  • REACT_APP_WEB_APP_N_URL - Target URL
  • REACT_APP_WEB_APP_N_ICON_PATH - Icon file path (relative to public/)

Example Icons: GitHub, Xero, Monday.com, Gmail, MailJet, Slack

Grafana Integration​

REACT_APP_GRAFANA_URLS=http://grafana1.local/d/abc,http://grafana2.local/d/xyz
REACT_APP_GRAFANA_LABELS=Network Monitoring,Service Health
REACT_APP_GRAFANA_API_KEY=your_grafana_api_key

Fields:

  • REACT_APP_GRAFANA_URLS - Comma-separated list of Grafana dashboard URLs
  • REACT_APP_GRAFANA_LABELS - Comma-separated list of dashboard names
  • REACT_APP_GRAFANA_API_KEY - Grafana API key for embedding

Usage: Embeds Grafana dashboards in the OmniCRM dashboard page.

Support URLs​

REACT_APP_FAQS_URL=https://support.yourcompany.com/faqs
REACT_APP_SUPPORT_URL=https://support.yourcompany.com

Purpose: Links to external support resources shown in the UI.

Social Logins​

REACT_APP_ALLOW_SOCIAL_LOGINS=yes

Options:

  • yes - Enable social login buttons (Google, Facebook, etc.)
  • no - Disable social logins

Note: Social login providers must be configured separately.

Top-Up and Recharge Configuration​

REACT_APP_TOPUP_PRICE_PER_DAY=10

Purpose: Sets the price per day for top-up/recharge services in the self-care portal.

Fields:

  • REACT_APP_TOPUP_PRICE_PER_DAY - Daily price for recharge services (numeric value)

Example: If set to 10 and currency is USD, customers pay $10 per day of service.

Note: This value must match the backend pricing configuration. See features_topup_recharge for complete setup details.

Applying Configuration Changes​

Backend (crm_config.yaml)​

  1. Edit OmniCRM-API/crm_config.yaml
  2. Save changes
  3. Restart the API service:
cd OmniCRM-API
sudo systemctl restart omnicrm-api
# or
./restart_api.sh

Changes take effect immediately after restart.

Frontend (.env)​

  1. Edit OmniCRM-UI/.env
  2. Save changes
  3. Rebuild the UI:
cd OmniCRM-UI
npm run build
  1. Restart the UI service or web server

Development Mode:

During development with npm start, restart the dev server to apply changes.

Configuration Best Practices​

Security​

  • Never commit secrets - Use .gitignore for config files with credentials
  • Use environment-specific configs - Separate dev/staging/production configs
  • Rotate secrets regularly - Update JWT secrets, API keys periodically
  • Limit API key permissions - Assign minimal necessary roles
  • Use IP whitelisting sparingly - Prefer API keys for better security

Maintenance​

  • Document changes - Keep changelog of configuration modifications
  • Backup configs - Store copies before major changes
  • Test in staging - Verify config changes before production deployment
  • Version control - Track config templates (without secrets) in git

Performance​

  • Use local database - Avoid remote database for better performance
  • Configure caching - Enable OCS caching if available
  • Optimize Grafana - Limit number of embedded dashboards

Branding​

  • Match colors - Ensure UI colors complement your logo
  • Test contrast - Verify text readability on colored backgrounds
  • Mobile testing - Check branding on mobile devices
  • Logo placement - Place company logos in OmniCRM-UI/public/resources/

Troubleshooting​

Changes not applied

  • Cause: Service not restarted or UI not rebuilt
  • Fix: Restart API/UI services after config changes

YAML syntax errors

  • Cause: Invalid YAML formatting (indentation, quotes, etc.)
  • Fix: Validate YAML online or use yamllint crm_config.yaml

Database connection failed

  • Cause: Wrong credentials or server unreachable
  • Fix: Verify database is running, credentials are correct

Stripe payments not working

  • Cause: Mismatched keys between backend and frontend
  • Fix: Ensure publishable_key matches in both files

Emails not sending

  • Cause: Invalid Mailjet credentials or template IDs
  • Fix: Verify Mailjet API key/secret, check template IDs exist
  • administration_api_keys - API key management
  • integrations_stripe - Stripe payment setup
  • integrations_mailjet - Email integration
  • concepts_api - API authentication
  • rbac - Role-based access control