> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/appertafoundation/openeyes/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="Core Common Configuration">
    Base system configuration (`protected/config/core/common.php`)
  </Step>

  <Step title="Core Environment Configuration">
    Environment-specific settings (`protected/config/core/main.php`, `test.php`, etc.)
  </Step>

  <Step title="Module Configurations">
    Each module's configuration files are loaded in sequence
  </Step>

  <Step title="Local Configuration">
    Local overrides (`protected/config/local/common.php`, `local/main.php`)
  </Step>
</Steps>

<Note>
  The configuration loading is managed by `OEConfig::getMergedConfig()` in `protected/config/OEConfig.php:40`.
</Note>

## Configuration Files

### Main Configuration Entry Point

**File:** `protected/config/main.php`

```php theme={null}
<?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

<Warning>
  Local configuration files are typically excluded from version control to protect sensitive information.
</Warning>

## Database Configuration

OpenEyes supports multiple methods for database configuration:

### 1. Legacy Configuration File

**File:** `/etc/openeyes/db.conf`

```ini theme={null}
host = localhost
port = 3306
dbname = openeyes
username = openeyes
password = your_password_here
```

### 2. Environment Variables

Recommended for containerized deployments:

```bash theme={null}
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:

```yaml theme={null}
secrets:
  DATABASE_USER:
    file: /run/secrets/DATABASE_USER
  DATABASE_PASS:
    file: /run/secrets/DATABASE_PASS
```

<Info>
  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`)
</Info>

## Environment Variables

### Database Settings

<ParamField path="DATABASE_HOST" type="string" default="localhost">
  MySQL/MariaDB host address
</ParamField>

<ParamField path="DATABASE_PORT" type="string" default="3306">
  Database server port
</ParamField>

<ParamField path="DATABASE_NAME" type="string" default="openeyes">
  Database name for OpenEyes
</ParamField>

<ParamField path="DATABASE_USER" type="string" default="openeyes">
  Database username
</ParamField>

<ParamField path="DATABASE_PASS" type="string" default="openeyes">
  Database password
</ParamField>

### Application Settings

<ParamField path="OE_MODE" type="string" default="DEV">
  Operating mode: `DEV`, `LIVE`, or `TEST`
</ParamField>

<ParamField path="OE_INSTITUTION_CODE" type="string" default="NEW">
  Institution identifier code
</ParamField>

<ParamField path="YII_DEBUG_BAR_IPS" type="string" default="*">
  IP addresses allowed to see debug bar (use `*` for all in development)
</ParamField>

<ParamField path="TZ" type="string" default="Europe/London">
  System timezone
</ParamField>

### Authentication Settings

<ParamField path="AUTH_SOURCE" type="string" default="BASIC">
  Authentication method: `BASIC`, `LDAP`, `SAML`, or `OIDC`
</ParamField>

<ParamField path="OE_LDAP_SERVER" type="string">
  LDAP server URL for LDAP authentication
</ParamField>

### Single Sign-On (SSO) Configuration

<ParamField path="SSO_BASE_URL" type="string" default="http://localhost">
  Base URL for SAML SSO
</ParamField>

<ParamField path="SSO_PROVIDER_URL" type="string">
  OIDC provider URL
</ParamField>

<ParamField path="SSO_CLIENT_ID" type="string">
  OIDC client identifier
</ParamField>

<ParamField path="SSO_CLIENT_SECRET" type="string">
  OIDC client secret (can also use Docker secret)
</ParamField>

<ParamField path="STRICT_SSO_ROLES_CHECK" type="boolean" default="false">
  Enforce strict role checking for SSO users
</ParamField>

### Password Policy Settings

<ParamField path="PW_ALLOW_CHANGE" type="boolean">
  Allow users to change their passwords
</ParamField>

<ParamField path="PW_RES_MIN_LEN" type="integer">
  Minimum password length
</ParamField>

<ParamField path="PW_RES_STRENGTH" type="string">
  Password complexity requirements
</ParamField>

<ParamField path="PW_STAT_DAYS_EXPIRE" type="integer">
  Days until password expires
</ParamField>

<ParamField path="PW_STAT_DAYS_LOCK" type="integer">
  Days until inactive account is locked
</ParamField>

### Portal Integration

<ParamField path="OE_PORTAL_ENABLED" type="boolean" default="FALSE">
  Enable patient portal integration
</ParamField>

<ParamField path="OE_PORTAL_URI" type="string">
  Internal portal URI
</ParamField>

<ParamField path="OE_PORTAL_EXTERNAL_URI" type="string">
  External portal URI for patient access
</ParamField>

## 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

<Info>
  The `SettingMetadata` model (`protected/models/SettingMetadata.php`) manages this hierarchy and provides caching for performance.
</Info>

### 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

```php theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="dollar-sign">
    Prefer environment variables over hardcoded values for deployment flexibility
  </Card>

  <Card title="Leverage Docker Secrets" icon="lock">
    Use Docker secrets for sensitive data in containerized environments
  </Card>

  <Card title="Don't Modify Core Files" icon="ban">
    Use local configuration files to override defaults
  </Card>

  <Card title="Version Control Carefully" icon="code-branch">
    Never commit sensitive data like passwords or API keys
  </Card>
</CardGroup>

## Configuration Examples

### Development Environment

```bash theme={null}
# .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

```bash theme={null}
# .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

```bash theme={null}
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](/admin/users-permissions)
* [Institution Configuration](/admin/institutions)
* [System Settings](/admin/system-settings)