System Configuration

Understanding OpenEyes configuration structure and management

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

Related Documentation

• User Management
• Institution Configuration
• System Settings