Skip to main content
OpenEyes uses a hierarchical configuration system built on the Yii PHP framework. Configuration is managed through PHP files and environment variables, providing flexibility for different deployment scenarios.

​
Configuration Architecture

OpenEyes loads configuration in a specific order, with later configurations overriding earlier ones:
1

Core Common Configuration

Base system configuration (protected/config/core/common.php)
2

Core Environment Configuration

Environment-specific settings (protected/config/core/main.php, test.php, etc.)
3

Module Configurations

Each module’s configuration files are loaded in sequence
4

Local Configuration

Local overrides (protected/config/local/common.php, local/main.php)
The configuration loading is managed by OEConfig::getMergedConfig() in protected/config/OEConfig.php:40.

​
Configuration Files

​
Main Configuration Entry Point

File: protected/config/main.php 
<?php
require_once dirname(__FILE__).'/OEConfig.php';
return OEConfig::getMergedConfig('main');
This file delegates to OEConfig which merges all configuration sources.

​
Core Common Configuration

File: protected/config/core/common.php Contains essential application settings:
  • Database Connection: Configuration for MySQL/MariaDB
  • Authentication Manager: Role-based access control (RBAC)
  • Application Components: Core services and utilities
  • Module Definitions: Active modules and their settings

​
Local Configuration

Local configurations allow you to override default settings without modifying core files:
  • protected/config/local/common.php - Common local settings
  • protected/config/local/main.php - Main application local overrides
  • protected/config/local/console.php - Console command overrides
Local configuration files are typically excluded from version control to protect sensitive information.

​
Database Configuration

OpenEyes supports multiple methods for database configuration:

​
1. Legacy Configuration File

File: /etc/openeyes/db.conf 
host = localhost
port = 3306
dbname = openeyes
username = openeyes
password = your_password_here

​
2. Environment Variables

Recommended for containerized deployments: 
DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_NAME=openeyes
DATABASE_USER=openeyes
DATABASE_PASS=your_password

​
3. Docker Secrets

Most secure option for Docker deployments: 
secrets:
  DATABASE_USER:
    file: /run/secrets/DATABASE_USER
  DATABASE_PASS:
    file: /run/secrets/DATABASE_PASS
The system checks for configuration in this order:
  1. /etc/openeyes/db.conf file
  2. Docker secrets in /run/secrets/
  3. Environment variables
  4. Default values
(See protected/config/core/common.php:30-40)

​
Environment Variables

​
Database Settings

​
DATABASE_HOST
string
default:"localhost"
MySQL/MariaDB host address
​
DATABASE_PORT
string
default:"3306"
Database server port
​
DATABASE_NAME
string
default:"openeyes"
Database name for OpenEyes
​
DATABASE_USER
string
default:"openeyes"
Database username
​
DATABASE_PASS
string
default:"openeyes"
Database password

​
Application Settings

​
OE_MODE
string
default:"DEV"
Operating mode: DEV, LIVE, or TEST
​
OE_INSTITUTION_CODE
string
default:"NEW"
Institution identifier code
​
YII_DEBUG_BAR_IPS
string
default:"*"
IP addresses allowed to see debug bar (use * for all in development)
​
TZ
string
default:"Europe/London"
System timezone

​
Authentication Settings

​
AUTH_SOURCE
string
default:"BASIC"
Authentication method: BASIC, LDAP, SAML, or OIDC
​
OE_LDAP_SERVER
string
LDAP server URL for LDAP authentication

​
Single Sign-On (SSO) Configuration

​
SSO_BASE_URL
string
default:"http://localhost"
Base URL for SAML SSO
​
SSO_PROVIDER_URL
string
OIDC provider URL
​
SSO_CLIENT_ID
string
OIDC client identifier
​
SSO_CLIENT_SECRET
string
OIDC client secret (can also use Docker secret)
​
STRICT_SSO_ROLES_CHECK
boolean
default:"false"
Enforce strict role checking for SSO users

​
Password Policy Settings

​
PW_ALLOW_CHANGE
boolean
Allow users to change their passwords
​
PW_RES_MIN_LEN
integer
Minimum password length
​
PW_RES_STRENGTH
string
Password complexity requirements
​
PW_STAT_DAYS_EXPIRE
integer
Days until password expires
​
PW_STAT_DAYS_LOCK
integer
Days until inactive account is locked

​
Portal Integration

​
OE_PORTAL_ENABLED
boolean
default:"FALSE"
Enable patient portal integration
​
OE_PORTAL_URI
string
Internal portal URI
​
OE_PORTAL_EXTERNAL_URI
string
External portal URI for patient access

​
Module Configuration

Each module can have its own configuration file: 
protected/modules/
  └── ModuleName/
      └── config/
          ├── common.php
          ├── main.php
          └── console.php
Module configurations are automatically discovered and merged when the module is enabled.

​
Settings Management

OpenEyes includes a comprehensive settings system managed through the database:

​
Setting Hierarchy

Settings can be defined at multiple levels (from most specific to least):
  1. User (setting_user) - User-specific settings
  2. Firm (setting_firm) - Context/firm-specific settings
  3. Institution + Subspecialty (setting_institution_subspecialty)
  4. Subspecialty (setting_subspecialty)
  5. Specialty (setting_specialty)
  6. Site (setting_site)
  7. Institution (setting_institution)
  8. Installation (setting_installation) - System-wide defaults
The SettingMetadata model (protected/models/SettingMetadata.php) manages this hierarchy and provides caching for performance.

​
Setting Metadata

Settings are defined in the setting_metadata table with:
  • key - Unique setting identifier
  • name - Display name
  • field_type_id - Input type (text, dropdown, checkbox, etc.)
  • default_value - Default value
  • data - Additional configuration (e.g., dropdown options)
  • lowest_setting_level - Minimum level at which setting can be overridden

​
Accessing Settings in Code

// Get a setting value
$value = SettingMetadata::model()->getSetting('setting_key');

// Get setting for specific element type
$value = SettingMetadata::model()->getSetting(
    'setting_key',
    $elementType
);

// Get setting name (with data mapping)
$displayValue = SettingMetadata::model()->getSettingName('setting_key');

​
Configuration Best Practices

Use Environment Variables

Prefer environment variables over hardcoded values for deployment flexibility

Leverage Docker Secrets

Use Docker secrets for sensitive data in containerized environments

Don't Modify Core Files

Use local configuration files to override defaults

Version Control Carefully

Never commit sensitive data like passwords or API keys

​
Configuration Examples

​
Development Environment

# .env file for docker-compose
OE_MODE=DEV
YII_DEBUG_BAR_IPS=*
DATABASE_HOST=db
DATABASE_NAME=openeyes_dev
DATABASE_USER=openeyes
DATABASE_PASS=openeyes
OE_TRAINING_MODE=true
OE_USER_BANNER_SHORT=Development

​
Production Environment

# .env file for docker-compose
OE_MODE=LIVE
DATABASE_HOST=production-db.internal
DATABASE_NAME=openeyes_prod
# Use Docker secrets for credentials
OE_INSTITUTION_CODE=HOSP
ENABLE_CRON=TRUE
HTTPS_ENABLE=TRUE
OUTPUT_APPLICATION_LOGS=TRUE

​
LDAP Authentication

AUTH_SOURCE=LDAP
OE_LDAP_SERVER=ldap://ldap.example.com:389
OE_LDAP_BIND_DN=cn=readonly,dc=example,dc=com
OE_LDAP_BIND_PASSWORD=secret
OE_LDAP_BASE_DN=ou=users,dc=example,dc=com

​
Troubleshooting

​
Configuration Not Loading

  1. Check file permissions on configuration files
  2. Verify PHP syntax in config files
  3. Check Docker logs: docker-compose logs web
  4. Ensure environment variables are properly set

​
Database Connection Issues

  1. Verify database credentials
  2. Check network connectivity to database host
  3. Ensure database exists and user has proper permissions
  4. Review protected/runtime/application.log

​
Module Not Loading

  1. Check module is listed in modules array
  2. Verify module path exists
  3. Check module’s config/common.php for errors
  4. Clear cache: ./yiic cache flush all

Build docs developers (and LLMs) love

Get started for freeTalk to us