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

---
name: oro-cloud
description: 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

```bash
orocloud-cli deploy                              # initial deployment
```

### Upgrades

```bash
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):

```bash
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

```bash
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

```bash
orocloud-cli maintenance:enable
orocloud-cli maintenance:disable
```

### Status & Logs

```bash
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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:
```yaml
orocloud_options:
    webserver:
        redirects_map:
            '/': '/home/'
```

**Staging** (`orocloud_stag.yaml`) -- restrict outbound email:
```yaml
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:

```yaml
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

```bash
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) |