planeMapper/.claude/skills/oro-devops/SKILL.md

name, description

name

description

oro-devops

OroCommerce DevOps and infrastructure reference covering system requirements, installation, deployment, Docker, cron setup, Supervisor, monitoring, caching, environment configuration, CI/CD, and performance optimization. Use when setting up local dev environments, configuring CI/CD, debugging deployment issues, or planning infrastructure. For OroCloud-specific operations (production deployment, upgrades, backups), see the oro-cloud skill.

OroCommerce DevOps

Infrastructure, deployment, and operations reference for OroCommerce. Docs: https://doc.oroinc.com/backend/setup/

Note: Production runs on OroCloud Enterprise. For cloud deployment, upgrades, backups, and maintenance commands, see the oro-cloud skill. This skill covers local dev, CI, and general infrastructure concepts.

System Requirements

Minimum Server

• 2 CPU cores, 2GB RAM, SSD
• Linux recommended (RHEL, Ubuntu, Debian, Oracle Linux)

Software Stack

Component	Version	Notes
PHP	>= 8.4	CLI + FPM
PostgreSQL	>= 16.1	with uuid-ossp extension
Nginx or Apache	latest	Nginx recommended
Node.js	>= 22	asset build only
NPM	> 10	asset build only
Redis	7.2.x	cache + sessions (recommended)
Elasticsearch	>= 8.4.1, < 9.0	EE only
RabbitMQ	3.12.x	EE only
Supervisor	latest	MQ consumer daemon
Gotenberg	>= 8.5	PDF generation (optional)

Required PHP Extensions

ctype, curl, fileinfo, gd, intl (ICU >= 4.4), json, mbstring, sodium, openssl, pgsql, pcre, simplexml, tokenizer, xml, zip, imap, soap, bcmath, ldap, mongodb (for GridFS)

PHP Settings

date.timezone = UTC
detect_unicode = Off
memory_limit = 1G
; Increase for schema updates:
max_execution_time = 300

Environment Configuration

Oro uses .env-app and .env-app.local for environment variables:

ORO_ENV=prod
ORO_SECRET=<random-secret>
ORO_DB_URL=postgres://user:pass@localhost:5432/oro_db?sslmode=disable&charset=utf8&serverVersion=17
ORO_MQ_DSN=amqp://user:pass@localhost:5672/%2f     # or dbal: for CE
ORO_SEARCH_URL=elastic-search://localhost:9200       # EE only
ORO_REDIS_URL=redis://localhost:6379
ORO_REDIS_CACHE_DSN=redis://localhost:6379/1
ORO_REDIS_DOCTRINE_DSN=redis://localhost:6379/2
ORO_REDIS_LAYOUT_DSN=redis://localhost:6379/3
ORO_SESSION_DSN=redis://localhost:6379/0
ORO_MAILER_DSN=smtp://localhost:1025
ORO_WEBSOCKET_SERVER_DSN=//0.0.0.0:8080
ORO_WEBSOCKET_FRONTEND_DSN=//*:8080/ws
ORO_WEBSOCKET_BACKEND_DSN=tcp://127.0.0.1:8080

Installation

# Install dependencies
composer install --prefer-dist --no-dev --optimize-autoloader

# Install application (creates DB schema, loads fixtures, builds assets)
php bin/console oro:install --env=prod \
    --organization-name="My Org" \
    --user-name=admin \
    --user-email=admin@example.com \
    --user-firstname=Admin \
    --user-lastname=Admin \
    --user-password=<password> \
    --application-url=https://app.example.com \
    --timeout=3600

Verify requirements: php bin/console oro:check-requirements -vv

Deployment Steps

# 1. Pull code
git pull origin main

# 2. Install dependencies
composer install --prefer-dist --no-dev --optimize-autoloader

# 3. Run migrations
php bin/console oro:migration:load --env=prod

# 4. Update extended entity schema
php bin/console oro:entity-extend:update-schema --env=prod

# 5. Clear and warmup cache
php bin/console cache:clear --env=prod
php bin/console oro:entity-extend:cache:warmup --env=prod

# 6. Build assets
php bin/console oro:assets:build --env=prod

# 7. Update cron definitions
php bin/console oro:cron:definitions:load --env=prod

# 8. Restart consumers
supervisorctl restart oro-consumer:*

Cron Setup

Single system crontab entry runs Oro's dispatcher every minute:

*/1 * * * * www-data /usr/bin/php /var/www/oro/bin/console oro:cron --env=prod > /dev/null

The oro:cron command dispatches scheduled commands to the MQ.

Message Queue Consumers

Use Supervisor to keep MQ consumers running:

# /etc/supervisor/conf.d/oro-consumer.conf
[program:oro-consumer]
command=/usr/bin/php /var/www/oro/bin/console oro:message-queue:consume --env=prod --memory-limit=512
process_name=%(program_name)s_%(process_num)02d
numprocs=2
autostart=true
autorestart=true
startsecs=5
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/oro/consumer_%(process_num)02d.log

Scale numprocs based on MQ load.

WebSocket Server

For real-time notifications:

[program:oro-websocket]
command=/usr/bin/php /var/www/oro/bin/console gos:websocket:server --env=prod
autostart=true
autorestart=true
user=www-data

Docker

Two Docker Compose Patterns

Pattern 1: Backing services only (CI / DDEV / local PHP)

docker-compose.yml at project root provides only infrastructure services. App runs on host or via DDEV/Symfony CLI:

services:
  pgsql:
    image: oroinc/pgsql:17.4-alpine
    ports: ['5432']
    environment:
      POSTGRES_USER: oro_db_user
      POSTGRES_DB: oro_db
      POSTGRES_PASSWORD: oro_db_pass
    volumes:
      - postgres:/var/lib/postgresql/data
    healthcheck:
      test: "pg_isready -U$${POSTGRES_USER} -d$${POSTGRES_DB}"
      interval: 5s
      timeout: 30s
      start_period: 40s
  redis:
    image: redis:7.4.2-alpine
    ports: ["6379"]
  elasticsearch:
    image: elasticsearch:8.17.4
    command: bin/elasticsearch -Eingest.geoip.downloader.enabled=false
    environment:
      discovery.type: "single-node"
      xpack.security.enabled: "false"
      ES_JAVA_OPTS: -Xms2g -Xmx2g
  rabbitmq:
    image: oroinc/rabbitmq:3.13.7-alpine
    ports: ['5672']
  mongodb:
    image: mongo:8.0.4
    ports: ["27017"]
  mailcatcher:
    image: schickling/mailcatcher
    ports: ['1025', '1080']

Pattern 2: Full stack (PHP-FPM + Nginx) for team/staging-like dev

Separate docker-compose in .docker/ with app container, nginx reverse proxy, Xdebug:

services:
  oro:
    build:
      context: ./php
      dockerfile: ./Dockerfile-6.1
    environment:
      COMPOSER_AUTH: '{"github-oauth": {"github.com": "${GITHUB_TOKEN}"}}'
      XDEBUG_SESSION: PHPSTORM
      PHP_IDE_CONFIG: "serverName=localdev.example.com"
    volumes:
      - ../:/usr/share/nginx/html
  nginx:
    image: nginx:stable-alpine
    ports: ["8280:80", "2443:443"]
    depends_on: [oro]
    volumes:
      - ../public:/usr/share/nginx/html/public
      - ./nginx/default.conf.template:/etc/nginx/templates/default.conf.template:ro
  postgres:
    image: postgres:16-alpine
    ports: ['25432:5432']
    volumes:
      - ./postgres/create_uuid-ossp_ext.sql:/docker-entrypoint-initdb.d/create_uuid-ossp_ext.sql
  rabbitmq:
    build:
      context: .
      dockerfile_inline: |
        FROM rabbitmq:3.12-management-alpine
        RUN wget -O $RABBITMQ_HOME/plugins/rabbitmq_delayed_message_exchange-3.12.0.ez \
          https://github.com/rabbitmq/rabbitmq-delayed-message-exchange/releases/download/v3.12.0/rabbitmq_delayed_message_exchange-3.12.0.ez && \
          rabbitmq-plugins enable --offline rabbitmq_delayed_message_exchange
    ports: ['25672:15672']

Notes:

• PostgreSQL requires uuid-ossp extension. Init script: CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
• RabbitMQ delayed message exchange plugin is required for Oro delayed messages
• Adminer (adminer:latest on port 28080) is useful for DB inspection during dev

Service Container Reference

Service	Image	Health Check
PostgreSQL	oroinc/pgsql:17.4-alpine	pg_isready
Redis	redis:7.4.2-alpine	redis-cli ping
Elasticsearch	elasticsearch:8.17.4	curl localhost:9200/_cluster/health
RabbitMQ	oroinc/rabbitmq:3.13.7-alpine	port 5672

Environment Files

Oro uses .env-app (not .env) as the primary env file:

File	Purpose
.env-app	Default values, committed to repo
.env-app.local	Local overrides (gitignored)
.env-app.test	Test-specific overrides

Key variable prefix: ORO_ (not APP_).

CI/CD (Jenkins Pattern)

Jenkins pipeline with parallel build stages:

stage('Build') {
    parallel {
        stage('Build:prod') {
            // composer install --no-dev, docker build, oro:install
        }
        stage('Build:test') {
            // composer install (with dev), phpcs, phpmd, unit tests, functional tests
        }
    }
}

Static analysis tools in CI:

• bin/phpcs --standard=PSR2 src/ (PHP CodeSniffer)
• bin/phpmd src/ xml vendor/oro/platform/build/phpmd.xml (PHP Mess Detector)
• Unit: phpunit --testsuite=unit src/
• Functional: phpunit --testsuite=functional src/

Image push to OroCloud registry: harborio.oro.cloud/{project}/orocommerce-enterprise-application:{tag}

Monitoring

Application Health

php bin/console oro:check-requirements -vv
php bin/console debug:router --env=prod    # verify routes
php bin/console oro:message-queue:consume --help  # MQ status

Key Metrics to Monitor

• MQ queue depth (DBAL: SELECT count(*) FROM oro_message_queue)
• Consumer process count (Supervisor)
• PHP-FPM pool status
• PostgreSQL connection count, slow queries
• Redis memory usage
• Elasticsearch cluster health
• Disk usage (cache, logs, file storage)

Logging

Oro uses Monolog (Symfony standard). Config in config/config_prod.yml. Docs: https://doc.oroinc.com/backend/logging/

Performance Optimization

• Enable OPcache for PHP
• Use Redis for cache + sessions (not filesystem)
• Use Elasticsearch for search (EE)
• Use RabbitMQ instead of DBAL transport (EE)
• Tune PostgreSQL (shared_buffers, work_mem, effective_cache_size)
• Use --no-debug for all prod commands
• Optimize Composer autoloader: composer dump-autoload --optimize
• Docs: https://doc.oroinc.com/backend/setup/system-requirements/performance-optimization/