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

# Quick Start Guide

> Get OpenEyes up and running in minutes using Docker Compose

## Get Started in Minutes

This quick start guide will help you set up OpenEyes for development using Docker Compose. This is the fastest way to get a working OpenEyes instance running on your machine.

<Note>
  This guide is for **development and testing purposes**. For production deployment, see the [Installation Guide](/installation).
</Note>

## Prerequisites

Before you begin, ensure you have the following installed:

<Steps>
  <Step title="Docker Desktop">
    Install Docker Desktop (includes Docker Compose)

    * **macOS/Windows**: [Download Docker Desktop](https://www.docker.com/products/docker-desktop)
    * **Linux**: Install Docker Engine and Docker Compose separately

    Verify installation:

    ```bash theme={null}
    docker --version
    docker compose version
    ```
  </Step>

  <Step title="Git">
    Install Git for cloning the repository

    ```bash theme={null}
    git --version
    ```
  </Step>

  <Step title="System Requirements">
    * **RAM**: Minimum 4GB (8GB recommended)
    * **Disk**: 10GB free space
    * **Ports**: 7777 (HTTP) and 7743 (HTTPS) available
  </Step>
</Steps>

## Quick Installation

<Steps>
  <Step title="Clone the Repository">
    Clone the OpenEyes repository from GitHub:

    ```bash theme={null}
    git clone https://github.com/AppertaFoundation/openeyes.git
    cd openeyes
    ```

    <Note>
      The default branch is `master` (stable). For bleeding-edge development, use `git checkout develop`
    </Note>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the `.devcontainer` directory:

    ```bash theme={null}
    cd .devcontainer
    touch .env
    ```

    Add the following configuration:

    ```bash .env theme={null}
    # Database Configuration
    MYSQL_ROOT_PASSWORD=openeyes
    DATABASE_HOST=db
    DATABASE_USER=openeyes
    DATABASE_PASS=openeyes

    # PHP Version (7.4, 8.0, or 8.1)
    PHP_VERSION=7.4

    # OpenEyes Configuration
    OE_MODE=DEV
    OE_INSTITUTION_CODE=NEW
    OE_USER_BANNER_SHORT=Local-Dev

    # Git Configuration (for your commits)
    GIT_USER=your-email@example.com

    # Timezone
    TZ=Europe/London

    # Development Features
    YII_DEBUG_BAR_IPS=*
    GENERATE_TEMP_SODIUM_CRYPTO_KEY=TRUE

    # Disable cron for development
    ENABLE_CRON=FALSE
    ```

    <Warning>
      The default passwords are for **development only**. Never use these in production!
    </Warning>
  </Step>

  <Step title="Start the Services">
    Launch the OpenEyes stack using Docker Compose:

    ```bash theme={null}
    docker compose up -d
    ```

    This will start two containers:

    * `db` - MySQL database with sample data
    * `web` - Apache/PHP web server with OpenEyes application

    Monitor the startup process:

    ```bash theme={null}
    docker compose logs -f web
    ```

    Wait for the message indicating the web server is ready (typically 2-3 minutes on first run).
  </Step>

  <Step title="Access OpenEyes">
    Once the containers are running, access OpenEyes in your browser:

    **HTTP**: [http://localhost:7777](http://localhost:7777)

    **HTTPS**: [https://localhost:7743](https://localhost:7743)

    <Note>
      Default login credentials:

      * **Username**: `admin`
      * **Password**: `admin` (or as configured in your sample database)
    </Note>
  </Step>
</Steps>

## Docker Compose Configuration

The development environment uses the following configuration from `.devcontainer/docker-compose.yml`:

<CodeGroup>
  ```yaml docker-compose.yml theme={null}
  version: '3.8'

  services:
    db:
      image: toukanlabsdocker/oe-sample-db:latest
      environment:
        MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-openeyes}
        TZ: "${TZ:-Europe/London}"
      command:
        - "--innodb_log_file_size=128M"
        - "--disable-log-bin"
        - "--max_allowed_packet=128M"
        - "--net_buffer_length=1000000"
        - "--default_authentication_plugin=mysql_native_password"

    web:
      image: toukanlabsdocker/oe-web-dev:php${PHP_VERSION:-7.4}
      environment:
        DATABASE_HOST: "${DATABASE_HOST:-db}"
        DATABASE_PASS: "${DATABASE_PASS:-openeyes}"
        DATABASE_USER: "${DATABASE_USER:-openeyes}"
        OE_MODE: ${OE_MODE:-DEV}
        OE_INSTITUTION_CODE: "${OE_INSTITUTION_CODE:-NEW}"
        YII_DEBUG_BAR_IPS: '*'
        XDEBUG_MODE: debug
      volumes:
        - "..:/var/www/openeyes:delegated"
      ports:
        - "7777:80"
        - "7743:443"
      depends_on:
        - "db"
  ```
</CodeGroup>

### Key Environment Variables

| Variable              | Default    | Description                      |
| --------------------- | ---------- | -------------------------------- |
| `PHP_VERSION`         | `7.4`      | PHP version (7.4, 8.0, or 8.1)   |
| `MYSQL_ROOT_PASSWORD` | `openeyes` | MySQL root password              |
| `DATABASE_HOST`       | `db`       | Database hostname                |
| `DATABASE_USER`       | `openeyes` | Database username                |
| `DATABASE_PASS`       | `openeyes` | Database password                |
| `OE_MODE`             | `DEV`      | Operating mode (DEV, TEST, LIVE) |
| `OE_INSTITUTION_CODE` | `NEW`      | Institution identifier           |
| `XDEBUG_MODE`         | `debug`    | Enable Xdebug for PHP debugging  |

## Common Development Tasks

### Running Database Migrations

Apply database schema changes:

```bash theme={null}
docker compose exec web php protected/yiic.php migrate --interactive=0
```

### Installing PHP Dependencies

Update Composer dependencies:

```bash theme={null}
docker compose exec web composer install
```

### Viewing Logs

Application logs:

```bash theme={null}
docker compose exec web tail -f /var/log/apache2/error.log
```

Database logs:

```bash theme={null}
docker compose logs -f db
```

### Accessing the Database

Connect to MySQL:

```bash theme={null}
docker compose exec db mysql -u openeyes -popeneyes openeyes
```

### Running Tests

Execute PHPUnit tests:

```bash theme={null}
docker compose exec web vendor/bin/phpunit protected/tests/
```

## Working with Modules

### Installing Additional Modules

Set the `MODULES` environment variable to automatically install specific modules:

```bash .env theme={null}
MODULES="OphInBiometry OphCoMessaging Genetics"
```

Restart the container:

```bash theme={null}
docker compose restart web
```

### Available Modules

Common modules included in OpenEyes:

* `OphCiExamination` - Clinical examination (core)
* `OphCoCorrespondence` - Letters and correspondence
* `OphDrPrescription` - Prescription management
* `OphCoTherapyapplication` - Therapy applications
* `OphInBiometry` - Biometry measurements
* `OphCoMessaging` - Internal messaging
* `Genetics` - Genetic testing workflows
* `PatientTicketing` - Queue management

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port Already in Use">
    If ports 7777 or 7743 are already in use, modify the port mappings in `docker-compose.yml`:

    ```yaml theme={null}
    ports:
      - "8080:80"   # Changed from 7777
      - "8443:443"  # Changed from 7743
    ```

    Then restart: `docker compose up -d`
  </Accordion>

  <Accordion title="Database Connection Failed">
    Ensure the database container is healthy:

    ```bash theme={null}
    docker compose ps
    docker compose logs db
    ```

    If needed, recreate the database:

    ```bash theme={null}
    docker compose down -v
    docker compose up -d
    ```
  </Accordion>

  <Accordion title="Permission Errors">
    Fix file permissions inside the container:

    ```bash theme={null}
    docker compose exec web chown -R www-data:www-data /var/www/openeyes/protected/runtime
    docker compose exec web chmod -R 775 /var/www/openeyes/protected/runtime
    ```
  </Accordion>

  <Accordion title="Composer Install Fails">
    Clear Composer cache and reinstall:

    ```bash theme={null}
    docker compose exec web composer clear-cache
    docker compose exec web composer install --no-cache
    ```
  </Accordion>
</AccordionGroup>

## Stopping the Environment

Stop containers (preserves data):

```bash theme={null}
docker compose stop
```

Stop and remove containers:

```bash theme={null}
docker compose down
```

Remove everything including volumes (⚠️ **deletes all data**):

```bash theme={null}
docker compose down -v
```

## Development Workflow

<Steps>
  <Step title="Make Code Changes">
    Edit files in your local repository. Changes are automatically synced to the container via volume mounts.
  </Step>

  <Step title="Test Changes">
    Refresh your browser to see changes. For PHP changes, no restart needed. For configuration changes, restart the web container:

    ```bash theme={null}
    docker compose restart web
    ```
  </Step>

  <Step title="Run Migrations">
    After database schema changes:

    ```bash theme={null}
    docker compose exec web php protected/yiic.php migrate
    ```
  </Step>

  <Step title="Commit Changes">
    Follow the gitflow model:

    * `master` - stable releases
    * `develop` - active development
    * `feature/*` - new features

    ```bash theme={null}
    git checkout develop
    git checkout -b feature/my-new-feature
    git commit -m "Add new feature"
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="server" href="/installation">
    Production installation and configuration
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the OpenEyes API
  </Card>

  <Card title="Contributing" icon="github" href="https://github.com/AppertaFoundation/openeyes">
    Contribute to OpenEyes development
  </Card>

  <Card title="Module Development" icon="puzzle-piece" href="/modules">
    Learn to create custom modules
  </Card>
</CardGroup>

<Warning>
  This development setup is **not suitable for production use**. See the [Installation Guide](/installation) for production deployment.
</Warning>