name: openemr-docker
description: This skill should be used when the user asks to "start openemr", "stop openemr", "openemr docker", "show openemr ports", "openemr status", or needs to manage the OpenEMR Docker development environment in a worktree.
version: 1.0.0

OpenEMR Docker Development Environment

Manage OpenEMR's Docker development environment for worktrees with automatic port assignment to avoid collisions.

Arguments

The skill accepts an optional action argument:
- /openemr-docker or /openemr-docker setup - Set up the environment (default)
- /openemr-docker start - Start the containers
- /openemr-docker stop - Stop the containers
- /openemr-docker down - Stop and remove containers
- /openemr-docker status - Show container status
- /openemr-docker ports - Show assigned ports
- /openemr-docker logs [service] - View logs (optionally for specific service)
- /openemr-docker shell - Open shell in openemr container

Prerequisites

Before running, verify:
1. Current directory is an OpenEMR worktree (has docker/development-easy/docker-compose.yml)
2. Docker is running

Setup Workflow

1. Detect worktree and generate project name

Get the worktree directory name for the project name:

echo "${PWD##*/}"

The project name should be openemr-<dirname> (sanitized: lowercase, alphanumeric and hyphens only).

2. Create .env file in worktree root

Create or update .env with the project name:

COMPOSE_PROJECT_NAME=openemr-<sanitized-dirname>

Important: Preserve any existing content in .env - only add/update the COMPOSE_PROJECT_NAME line.

3. Create compose.override.yml in worktree root

Create the override file with all ports set to 0 for automatic assignment. Important: Use !override to completely replace the port mappings from the base file instead of merging them:

services:
  mysql:
    ports: !override
      - "0:3306"
  openemr:
    ports: !override
      - "0:80"
      - "0:443"
  selenium:
    ports: !override
      - "0:4444"
      - "0:7900"
  phpmyadmin:
    ports: !override
      - "0:80"
  couchdb:
    ports: !override
      - "0:5984"
      - "0:6984"
  mailpit:
    ports: !override
      - "0:8025"
      - "0:1025"

4. Add to .gitignore

Ensure these files are gitignored (add if not present):
- compose.override.yml
- .env (if not already ignored)

Check existing .gitignore first to avoid duplicates.

5. Confirm setup

Report what was created and show the user how to start:
- Project name that will be used
- Files created/updated
- Command to start: /openemr-docker start

Start Workflow

Run docker compose with both files:

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml up --detach --wait

After containers are healthy, automatically show ports with the ports workflow.

Stop Workflow

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml stop

Down Workflow

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml down

Ask user if they want to remove volumes too (down -v).

Status Workflow

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml ps

Ports Workflow

Get the assigned ports for key services:

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port openemr 80
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port openemr 443
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port mysql 3306
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port phpmyadmin 80
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port couchdb 5984
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port mailpit 8025
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port selenium 4444
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml port selenium 7900

Format the output as a table showing:
- Service name
- URL (for web services) or connection string (for databases)
- Credentials where applicable

Example output format:

OpenEMR Ports:

Service       URL/Connection                    Credentials
-----------   -------------------------------   ----------------
OpenEMR       http://localhost:52341            admin / pass
              https://localhost:52342
phpMyAdmin    http://localhost:52343
MySQL         localhost:52344                   root / root
Mailpit       http://localhost:52345
CouchDB       http://localhost:52346            admin / password
Selenium      http://localhost:52347
VNC           http://localhost:52348            openemr123

Logs Workflow

# All services
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml logs -f

# Specific service
docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml logs -f <service>

Shell Workflow

docker compose -f docker/development-easy/docker-compose.yml -f compose.override.yml exec openemr bash

Known Limitations

• The OPENEMR_SETTING_site_addr_oath environment variable in the base compose file is hardcoded to https://localhost:9300. OAuth features may not work correctly with dynamic ports. If OAuth is needed, manually update this value after getting the assigned HTTPS port.

Notes

• Always use both -f flags to ensure the override is applied
• The .env file sets COMPOSE_PROJECT_NAME which Docker Compose reads automatically
• Relative paths in the base compose file resolve relative to that file's location, so they work correctly
• Volumes are namespaced by project name, so each worktree has isolated data
• The !override YAML directive is required for ports - without it, Docker Compose merges the port lists instead of replacing them, causing conflicts with the hardcoded ports in the base file