Skip to main content

​
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)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=[email protected]

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

VariableDefaultDescription
PHP_VERSION7.4PHP version (7.4, 8.0, or 8.1)
MYSQL_ROOT_PASSWORDopeneyesMySQL root password
DATABASE_HOSTdbDatabase hostname
DATABASE_USERopeneyesDatabase username
DATABASE_PASSopeneyesDatabase password
OE_MODEDEVOperating mode (DEV, TEST, LIVE)
OE_INSTITUTION_CODENEWInstitution identifier
XDEBUG_MODEdebugEnable 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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us