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

name, description

name	description
oro-cloud	OroCloud Enterprise Cloud operations reference covering deployment, upgrades, maintenance commands, backups, environment configuration, monitoring, and cloud architecture. Use when deploying to OroCloud, running maintenance operations, configuring cloud environments, troubleshooting cloud deployments, or planning cloud infrastructure.

OroCommerce Cloud (OroCloud)

Operations and maintenance reference for OroCloud Enterprise environments. Docs: https://doc.oroinc.com/cloud/

Architecture Overview

OroCloud runs on GCP or OCI with fully redundant infrastructure:

Component	Details
CDN/LB	GCP CDN or Cloudflare (DDoS protection, edge caching)
Web Nodes	>= 2 nodes across availability zones, Nginx + PHP-FPM
Database	PostgreSQL with automatic failover (primary + secondary zone)
Search	Elasticsearch cluster (EE)
Message Queue	RabbitMQ cluster (EE)
Cache	Redis Sentinel cluster
File Storage	GridFS clustered (MongoDB)
SMTP	Dedicated SMTP relay (multi-relay HA)

All resources within a single region, distributed across zones.

EE-Specific Stack (Always Available)

Since this is Enterprise Cloud, these are always available (not optional):

• Elasticsearch >= 8.4.1 for search indexing (ORO_SEARCH_URL)
• RabbitMQ 3.12.x for message queue (ORO_MQ_DSN=amqp://...)
• Redis 7.2.x for cache + sessions
• GridFS (MongoDB) for file storage
• Organization Types for multi-org feature restrictions
• Field ACL for field-level permissions

Maintenance Tool (orocloud-cli)

All operations on OroCloud environments use orocloud-cli.

Deployment

orocloud-cli deploy                              # initial deployment

Upgrades

orocloud-cli upgrade                             # with downtime (full)
orocloud-cli upgrade:rolling                     # no downtime (safe for minor versions)
orocloud-cli upgrade:source                      # code-only, no platform:update

Rolling/source upgrades: safe only when DB schema doesn't change. Do NOT drop tables/columns or alter column types during rolling upgrades.

Application Packages (v5.0+)

Prebuilt packages shared across environments (dev/stag/uat/prod):

orocloud-cli app:package:build 5.1.0 --label="GA Release"
orocloud-cli app:package:list
orocloud-cli app:package:deploy --rolling harborio.oro.cloud/proj-stag1/orocommerce:5_1_0
orocloud-cli app:package:upgrade --rolling 5.1.0

Significantly faster than standard upgrade (400s vs 1300s).

Backups

orocloud-cli backup:create [--label=my-backup]
orocloud-cli backup:list
orocloud-cli backup:restore {backup_id}

Automatic backup schedule:

• Hourly (retained 7 days)
• Weekly (retained 4 weeks)
• Monthly (retained 12 months)

Encrypted with AES-256. RTO: 30 min to several hours.

Maintenance Mode

orocloud-cli maintenance:enable
orocloud-cli maintenance:disable

Status & Logs

orocloud-cli log:list
orocloud-cli log:view {log_file}
orocloud-cli config:validate
orocloud-cli config:help

Environment Configuration (orocloud.yaml)

All configuration managed via orocloud.yaml in the repository root. Docs: https://doc.oroinc.com/cloud/maintenance/advanced-use/

The maintenance agent merges three YAML files:

1. /mnt/{ocom}/app/orocloud.yaml (host-level)
2. /mnt/{ocom}/app/www/orocloud.yaml (repo root, common to all envs)
3. /mnt/{ocom}/app/www/orocloud_{dev,stag,uat,prod}.yaml (env-specific)

Changes auto-applied within 10 minutes or on next deployment. Validate: orocloud-cli config:validate

Important: Use single quotes only (no double quotes). Use spaces, not tabs.

Deployment Configuration

orocloud_options:
    deployment:
        install_commands:
            - 'oro:install --sample-data=n --user-name=admin ...'
        upgrade_commands:
            - 'oro:platform:update'
        pre_upgrade_commands:
            - 'oro:maintenance-notification --message=Deploy\ start'
        post_upgrade_commands:
            - 'oro:maintenance-notification --message=Deploy\ finish'
        pre_maintenance_commands: []   # before maintenance lock
        post_maintenance_commands: []  # after maintenance unlock
        composer_command: '{{composer_cmd}} install --no-dev --optimize-autoloader'
        git_clone_recursive: true
        db_extensions:
            - 'uuid-ossp'
            - 'pgcrypto'
        before_backup_create_commands: []
        after_backup_create_commands: []

Application Configuration

orocloud_options:
    application:
        maintenance_page: 'public/maintenance.html'
        error_pages:
            403: 'public/403.html'
            502: 'public/502.html'
        web_backend_prefix: '/admin'
        consumers_debug_mode: false
        env_vars:
            COMPOSER_AUTH: '{"http-basic":{"repo.example.com":{"username":"u","password":"p"}}}'

Webserver Configuration

orocloud_options:
    webserver:
        header_x_frame: true
        redirects_map:
            '/old-url': '/new-url'
        redirects_map_include:
            - 'redirects/website1.yml'
        locations:
            'root':
                type: 'php'
                location: '~ /index\.php(/|$)'
                auth_basic_enable: true
                auth_basic_userlist:
                    user1: { ensure: 'present', password: 'pass' }
                allow: ['127.0.0.1']
                deny: ['all']
            'admin':
                type: 'php'
                location: '~ /index\.php/admin(/|$)'
                auth_basic_enable: true
                auth_basic_userlist:
                    admin: { ensure: 'present', password: 'pass' }
        access_policy:
            'ip':
                'type': 'allow'
                'allow': ['192.168.0.0/16']
                'deny': ['10.0.0.1']
            'country':
                'type': 'deny'
                'allow': ['US', 'CA']
            'ua':
                'deny': ['AcoiRobot', 'Wget']
        limit_whitelist:
            - '8.8.8.8'
        limit_whitelist_uri:
            - '~(^/api/(.*))'
        newrelic_options:
            license_key: '<key>'
        blackfire_options:
            agent_enabled: true
            server_id: '<id>'
            server_token: '<token>'

Location types: php, static, rewrite. WAF: IP/ASN/country/user-agent filtering + rate limiting + bot detection. HTTP 451 returned for WAF blocks.

Scheduled Tasks

orocloud_options:
    schedule:
        'my_task':
            command: 'orocloud-cli app:console "my:command"'
            minute: '*/5'
            hour: '*'

Environment Variables

Set via orocloud_options.application.env_vars. Standard Oro env vars (ORO_DB_URL, ORO_MQ_DSN, etc.) are pre-configured. Never set empty values (ORO_VAR= or ORO_VAR=NULL); omit the variable instead.

Per-Environment Configuration

Use environment-specific YAML files (recommended approach):

orocloud.yaml         # common to all environments
orocloud_dev.yaml     # dev-only overrides
orocloud_stag.yaml    # staging-only overrides
orocloud_prod.yaml    # production-only overrides

Real-World Examples

Production (orocloud.yaml) -- redirect root to storefront:

orocloud_options:
    webserver:
        redirects_map:
            '/': '/home/'

Staging (orocloud_stag.yaml) -- restrict outbound email:

orocloud_options:
    mail:
        whitelist:
            - 'yourcompany.com'
            - 'agency.com'

Cloud-Specific Symfony Config (config_cloud.yml)

For OroCloud deployments, create config/config_cloud.yml importing prod config:

imports:
    - { resource: config_prod.yml }

parameters:
    env(ORO_LOG_PATH): "php://stderr"
    env(ORO_MULTIHOST_ENABLED): true

    sftp_root_path: '%env(ORO_SFTP_ROOT_PATH)%'
    env(ORO_SFTP_ROOT_PATH): '%kernel.project_dir%/var/sftp'

    gaufrette_adapter.public: 'gridfs:%env(ORO_MONGODB_DSN_PUBLIC)%'
    gaufrette_adapter.private: 'gridfs:%env(ORO_MONGODB_DSN_PRIVATE)%'
    gaufrette_adapter.import_files: 'local:%env(ORO_IMPORT_EXPORT_PATH)%'

    env(APP_RUNTIME): Oro\Bundle\DistributionBundle\Runtime\CloudRuntime

Key differences from self-hosted prod:

• Logs to stderr (captured by cloud infra)
• File storage via GridFS (not local filesystem)
• Cloud-specific runtime class
• SFTP root path for file-based imports

Docs: https://doc.oroinc.com/cloud/maintenance/dif-environments/

Patching

orocloud-cli patch:apply /path/to/patch.diff           # dry-run by default
orocloud-cli patch:apply /path/to/patch.diff --force   # actually apply
orocloud-cli patch:list
orocloud-cli patch:view /path/to/applied.patch
orocloud-cli patch:revert /path/to/applied.patch --force

Patches removed on upgrade. Composer patches plugin (cweagans/composer-patches) also supported for vendor package patches. Docs: https://doc.oroinc.com/cloud/maintenance/patches/

Cron & Consumers

Cron and MQ consumers are managed by Oro's infrastructure. Only consumers running before an upgrade will restart after. Custom cron via CronCommandScheduleDefinitionInterface or orocloud.yaml schedule. Custom scheduled tasks via orocloud_options.schedule. Docs: https://doc.oroinc.com/cloud/maintenance/scheduled-tasks/

Security

Docs: https://doc.oroinc.com/cloud/security/

• Network segmentation: Application subnet (isolated) + Maintenance DMZ subnet
• No public IPs on application nodes; traffic via LB or Cloudflare tunnel only
• VPN access: OpenVPN with MFA for maintenance SSH (port 31194 UDP)
• WAF: Bot detection (testcookie), request scanning (Naxsi), rate limiting
• PCI-DSS certified (yearly reassessment)
• TLS termination: at Cloudflare or GCP LB; HTTPS to app nodes not required

Access policy configurable via orocloud.yaml access_policy section (IP, ASN, country, user-agent filtering).

Monitoring

Docs: https://doc.oroinc.com/cloud/monitoring/

Oro monitors internally (no customer access to internal alerts):

• OS metrics: CPU, disk, RAM, swap, network, process count
• Component metrics: Nginx, PostgreSQL, Redis, RabbitMQ, Elasticsearch
• Application metrics: web checks, SSL, DNS, HTTP status, error rates, MQ queues/consumers, orders/users/SKU statistics

Customer-available monitoring:

• GCP Operations Suite: uptime checks, OS metrics (Metrics Explorer)
• NewRelic and Blackfire: supported with your own license
• Logs: orocloud-cli log:list / log:view

Incident response: warning (routine) and critical (incident) thresholds. Customers notified by email for incidents.

Disaster Recovery

• Cold DR location (different IaaS region)
• RPO: last daily backup
• Minimum RTO: 60 minutes
• Automatic DNS failover (if Oro-managed domain)
• Primary and DR IPs provided at onboarding
• DR approval required from customer before activation

Key Differences from Self-Hosted

Aspect	Self-Hosted	OroCloud
Deployment	Manual or CI/CD	orocloud-cli upgrade
Elasticsearch	Optional (EE)	Always available (cluster)
RabbitMQ	Optional (EE)	Always available (cluster)
File Storage	Local FS	GridFS (MongoDB cluster)
Backups	Your responsibility	Automated (hourly/weekly/monthly)
SSL/CDN	Your config	Managed (GCP CDN or Cloudflare)
Scaling	Manual	Managed by Oro team
Patching	Direct server access	orocloud-cli patch:apply
Monitoring	Your tooling	Included (+ GCP suite, NewRelic, Blackfire)
WAF	Your config	Included (bot detection, rate limiting, geo-blocking)
Security	Your responsibility	PCI-DSS certified, VPN + MFA
Config	Server files	orocloud.yaml (validated, versioned)