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.

This guide is for development and testing purposes. For production deployment, see the Installation Guide.

Prerequisites

Before you begin, ensure you have the following installed:

1. Docker Desktop

   Install Docker Desktop (includes Docker Compose)

   • macOS/Windows: Download Docker Desktop
   • Linux: Install Docker Engine and Docker Compose separately

   Verify installation:

   docker --version
   docker compose version
   
2. Git

   Install Git for cloning the repository

   git --version
   
3. System Requirements

   • RAM: Minimum 4GB (8GB recommended)
   • Disk: 10GB free space
   • Ports: 7777 (HTTP) and 7743 (HTTPS) available

Quick Installation

1. Clone the Repository

   Clone the OpenEyes repository from GitHub:

   git clone https://github.com/AppertaFoundation/openeyes.git
   cd openeyes
   

   The default branch is master (stable). For bleeding-edge development, use git checkout develop

2. Configure Environment Variables

   Create a .env file in the .devcontainer directory:

   cd .devcontainer
   touch .env
   

   Add the following configuration:

   .env

   # 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=[e-mail]
   
   # Timezone
   TZ=Europe/London
   
   # Development Features
   YII_DEBUG_BAR_IPS=*
   GENERATE_TEMP_SODIUM_CRYPTO_KEY=TRUE
   
   # Disable cron for development
   ENABLE_CRON=FALSE
   

   The default passwords are for development only. Never use these in production!

3. Start the Services

   Launch the OpenEyes stack using Docker Compose:

   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:

   docker compose logs -f web
   

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

4. Access OpenEyes

   Once the containers are running, access OpenEyes in your browser:

   HTTP: http://localhost:7777

   HTTPS: https://localhost:7743

   Default login credentials:

   • Username: admin
   • Password: admin (or as configured in your sample database)

Docker Compose Configuration

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

docker-compose.yml

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"

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:

docker compose exec web php protected/yiic.php migrate --interactive=0

Installing PHP Dependencies

Update Composer dependencies:

docker compose exec web composer install

Viewing Logs

Application logs:

docker compose exec web tail -f /var/log/apache2/error.log

Database logs:

docker compose logs -f db

Accessing the Database

Connect to MySQL:

docker compose exec db mysql -u openeyes -popeneyes openeyes

Running Tests

Execute PHPUnit tests:

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:

.env

MODULES="OphInBiometry OphCoMessaging Genetics"

Restart the container:

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

Port Already in Use

If ports 7777 or 7743 are already in use, modify the port mappings in docker-compose.yml:

ports:
  - "8080:80"   # Changed from 7777
  - "8443:443"  # Changed from 7743

Then restart: docker compose up -d

Database Connection Failed

Ensure the database container is healthy:

docker compose ps
docker compose logs db

If needed, recreate the database:

docker compose down -v
docker compose up -d

Permission Errors

Fix file permissions inside the container:

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

Composer Install Fails

Clear Composer cache and reinstall:

docker compose exec web composer clear-cache
docker compose exec web composer install --no-cache

Stopping the Environment

Stop containers (preserves data):

docker compose stop

Stop and remove containers:

docker compose down

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

docker compose down -v

Development Workflow

1. Make Code Changes

   Edit files in your local repository. Changes are automatically synced to the container via volume mounts.

2. Test Changes

   Refresh your browser to see changes. For PHP changes, no restart needed. For configuration changes, restart the web container:

   docker compose restart web
   
3. Run Migrations

   After database schema changes:

   docker compose exec web php protected/yiic.php migrate
   
4. Commit Changes

   Follow the gitflow model:

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

   git checkout develop
   git checkout -b feature/my-new-feature
   git commit -m "Add new feature"
   

Next Steps

Installation Guide

Production installation and configuration

API Reference

Explore the OpenEyes API

Contributing

Contribute to OpenEyes development

Module Development

Learn to create custom modules

This development setup is not suitable for production use. See the Installation Guide for production deployment.